Unknown - haskell-notes

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

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 :: Numa =>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

В первом варианте мы заключаем блок кода в окружение ...@@. Так мы можем выделить целый кусок

кода. Для выделения одной строки мы можем воспользоваться знаком >.

Примеры вычисления в интерпретаторе

В Haddockмы можем привести пример вычисления выражения в интерпретаторе. Это делается с помощью

тройного символа >:

-- | Two examples are given bellow:

--

-- >>> 2+3

-- 5

--

-- >>> print 1 >> print 2

-- 1

-- 2

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

в интерпретаторе.

Имена определений

Для того чтобы выделить имя любого определения, будь то функция, тип или класс, необходимо заклю-

чить его в ординарные кавычки, как в ’T’. При этом Haddockустановит ссылку к определению и подсветит

имя в тексте. Для того чтобы сослаться на определение из другого модуля необходимо написать его полное