Учебник по Haskell

именем пакета мы видим краткое описание, оно берётся из атрибута Synopsis. Если мы зайдём на страницу

одного из пакетов, то там мы увидим страницу в таком же формате, что и документация к стандартным

библиотекам. Мы видим описание пакета и ниже иерархию модулей. Мы можем зайти в заинтересовавший

нас модуль и посмотреть на объявленные функции, типы и классы. В самом низу страницы находится ссылка

к исходникам пакета.

“Домашняя страница” пакета была создана с помощью приложения Haddock. Оно генерирует документа-

цию в формате html по специальным комментариям. Haddock встроен в cabal, например мы можем сделать

документацию к нашему пакету hello. Для этого нужно переключиться на корневую директорию пакета и

вызвать:

270 | Глава 18: Средства разработки

cabal haddock

После этого в директории dist появится директория doc, в которой внутри директории html находится

созданная документация. Мы можем открыть файл index. html и там мы увидим “иерархию нашего” модуля.

В модуле пока нет ни одной функции, так получилось потому, что Haddock помещает в документацию лишь

те функции, у которых есть объявление типа. Если мы добавим в модуле Hello. hs: к единственной функции

объявление типа:

helloWorld :: String

helloWorld = hello ++ ”, ” ++ world ++ ”!”

И теперь перезапустим haddock. То мы увидим, что в модуле Hello появилась одна запись.

Комментарии к определениям

Прокомментировать любое определение можно с помощью комментария следующего вида:

-- | Here is the comment

helloWorld :: String

helloWorld = hello ++ ”, ” ++ world ++ ”!”

Обратите внимание на значок “или”, сразу после комментариев. Этот комментарий будет включен в

документацию. Также можно писать комментарии после определения для этого к комментарию добавляется

значок степени:

helloWorld :: String

helloWorld = hello ++ ”, ” ++ world ++ ”!”

-- ^ Here is the comment

К сожалению на момент написания этих строк Haddock может включать в документацию лишь латинские

символы. Комментарии могут простираться несколько строк:

-- | Here is the type.

-- It contains three elements.

-- That’s it.

data T = A | B | C

Также они могут быть блочными:

{-|

Here is the type.

It contains three elements.

That’s it.

-}

data T = A | B | C

Мы можем комментировать не только определение целиком, но и отдельные части. Например так мы

можем пояснить отдельные аргументы у функции:

add :: Num a => a

-- ^ The first argument

-> a

-- ^ The second argument

-> a

-- ^ The return value

Методы класса и отдельные конструкторы типа можно комментировать как обычные функции:

data T

-- | constructor A

= A

-- | constructor B

| B

-- | constructor C

| C

Или так:

Создание документации с помощью Haddock | 271

data T = A

-- ^ constructor A

| B

-- ^ constructor B

| C

-- ^ and so on

Комментарии к классу:

-- | С-class

class С a where

-- | f-function

f :: a -> a

-- | g-function

g :: a -> a

Комментарии к модулю

Комментарии к модулю помещаются перед объявлением имени модуля. Эта информация попадёт в самое

начало страницы документации:

-- | Little example

module Hello where

Структура страницы документации

Если модуль большой, то его бывает удобно разделить на части, словно разделы в главе книги. Определе-

ния группируются по функциональности и помещаются в разные разделы или даже подразделы. Структура

документации определяется с помощью специальных комментариев в экспорте модуля. Посмотрим на при-

мер:

-- | Little example

module Hello(

-- * Introduction

-- | Here is the little example to show you

-- how to make docs with Haddock

-- * Types

-- | The types.

T(.. ),

-- * Classes

-- | The classes.

C(.. ),

-- * Functions

helloWorld

-- ** Subfunctions1

-- ** Subfunctions2

) where

...

Комментарии со звёздочкой создают раздел, а с двумя звёздочками – подраздел. Те определения, ко-

торые экспортируются за комментариями со звёздочкой попадут в один раздел или подраздел. Если сразу

за комментарием со звёздочкой идёт комментарий со знаком “или”, то он будет помещён в самое начало

раздела. В нём мы можем пояснить по какому принципу группируются определения в данном разделе.

Разметка

С помощью специальных символов можно выделять различные элементы текста, например, ссылки, куски

кода, названия определений или модулей. Haddock установит необходимые ссылки и выделит элемент в

документации.

При этом символы \, ’, ‘, ”, @, < являются специальными, если вы хотите воспользоваться одним из

специальных символов в тексте необходимо написать перед ним обратный слэш \. Также символы для обо-

значения комментариев *, |, ^ и > являются специальными, если они расположены в самом начале строки.

272 | Глава 18: Средства разработки

Параграфы

Параграфы определяются по пустой сроке в комментарии. Так например мы можем разбить текст на два

параграфа:

-- | The first paragraph goes here.

--

-- The second paragraph goes here.

fun :: a -> b

Блоки кода

Существует два способа обозначения блоков кода: