К какой категории какой пакет относится мы указываем в . cabal-файле в атрибуте Category. Далее рядом с
именем пакета мы видим краткое описание, оно берётся из атрибута 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
Блоки кода
Существует два способа обозначения блоков кода:
— | This documentation includes two blocks of code:
—
— @
—
f x = x + x
—
g x = x
— @
—
— >
g x = x * 42
В первом варианте мы заключаем блок кода в окружение …@@. Так мы можем выделить целый кусок