— | 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 установит ссылку к определению и подсветит
имя в тексте. Для того чтобы сослаться на определение из другого модуля необходимо написать его полное
имя, то есть с приставкой имени модуля, например функция fun, определённая в модуле M, имеет полное
имя M. fun, тогда в комментариях мы обозначаем её ’M.fun’.
Ординарные кавычки часто используются в английском языке как апострофы, в таких сочетаниях как
don’t, isn’t. Перед такими вхождениями ординарных кавычек можно не писать обратный слэш. Haddock сумеет
отличить их от идентификатора.
Курсив и моноширинный шрифт
Для выделения текста курсивом, он заключается в окружение … . Для написания текста моноширинным
шрифтом, он заключается в окружение …@@.
Модули
Для обозначения модулей используются двойные кавычки, как в
— | This is a reference to the ”Foo” module.
Создание документации с помощью Haddock | 273
Списки
Список без нумерации обозначается с помощью звёздочек:
— | This is a bulleted list:
—
—
* first item
—
—
* second item
Пронумерованный список, обозначается символами (n) или n. (n с точкой), где n – некоторое целое
число:
— | This is an enumerated list:
—
—
(1) first item
—
—
2. second item
Список определений
Определения обозначаются квадратными скобками, например комментарий:
— | This is a definition list:
—
—
[@foo@] The description of @foo@.
—
—
[@bar@] The description of @bar@.
в документации будет выглядеть так:
foo The description of foo.
bar The description of bar.
Для выделения текста моноширинным шрифтом мы воспользовались окружением …@@.
URL
Ссылки на сайты включаются с помощью окружения .
Ссылки внутри модуля
Для того чтобы сослаться на какой-нибудь текст внутри модуля, его необходимо отметить ссылкой. Для
этого мы помещаем в том месте, на которое мы хотим сослаться, запись #label#, где label – это идентифика-
тор ссылки. Теперь мы можем сослаться на это место из другого модуля с помощью записи ” module#label”,
где module – имя модуля, в котором находится ссылка label.
18.3 Краткое содержание
В этой главе мы познакомились с основными элементами арсенала разработчика программ. Мы научи-
лись создавать библиотеки и документировать их.
18.4 Упражнения
Вспомните один из примеров и превратите его в библиотеку. Например, напишите библиотеку для нату-
ральных чисел Пеано.
274 | Глава 18: Средства разработки
Глава 19
Ориентируемся по карте
Рассмотрим задачу поиска маршрута на карте. У нас есть карта метро и нам нужно проложить маршрут
от одной станции к другой. Карта метро~– это граф, узлы обозначают станции, а рёбра соединяют соседние
станции. Предположим, что мы знаем расстояния между всеми станциями и нам надо найти кратчайший
путь от станции площадь Баха до станции Таинственный лес (рис. 19.1).
Космодром
Запад
Таинственный
лес
Призрак
Инева
ул.Булычёва
Троллев мост
Тилль
Сириус
Звезда
Север
Лао
Юг
Де
пл.Баха
Крест
пл.Шекспира
Дно болота
Родник
Восток
Рис. 19.1: Схема метрополитена
Давайте переведём этот рисунок на Haskell. Сначала опишем имена линий и станций:
module Metro where
data Station = St Way Name
deriving (Show, Eq)
data Way = Blue | Black | Green | Red | Orange
deriving (Show, Eq)
data Name = Kosmodrom | UlBylichova | Zvezda
| Zapad | Ineva | De | Krest | Rodnik | Vostok
| Yug | Sirius | Til | TrollevMost | Prizrak | TainstvenniyLes
| DnoBolota | PlBakha | Lao | Sever
| PlShekspira
deriving (Show, Eq)
Предположим, что нам известны координаты каждой из станций. По ним мы можем вычислять расстояние
между станциями по прямой:
| 275
data Point = Point
{ px :: Double
, py :: Double
} deriving (Show, Eq)
place :: Name -> Point
place x = uncurry Point $ case x of
Kosmodrom
-> (—3,7)
UlBylichova
-> (—2,4)
Zvezda
-> (0,1)
Zapad
-> (1,7)
Ineva
-> (0.5, 4)
De
-> (0, —1)
Krest
-> (0, —3)
Rodnik
-> (0, —5)
Vostok
-> (—1, —7)
Yug
-> (—7, —1)
Sirius
-> (—3,0)
Til
-> (3,2)
TrollevMost
-> (5,4)
Prizrak
-> (8,6)
TainstvenniyLes
-> (11,7)
DnoBolota
-> (—7, —4)
PlBakha
-> (—3, —3)
Lao
-> (3.5,0)
Sever
-> (6,1)
PlShekspira
-> (3, —3)
dist :: Point -> Point -> Double
dist a b = sqrt $ (px a — px b)^2 + (py a — py b)^2
stationDist :: Station -> Station -> Double
stationDist (St n a) (St m b)
| n /= m && a == b
= penalty
| otherwise
= dist (place a) (place b)
where penalty = 1
Расстояние между точками вычисляется по формуле Евклида (dist). Если у станций одинаковые имена,
но они расположены на разных линиях мы будем считать, что расстояние между ними равно единице. Теперь
нам необходимо описать связность станций. Мы опишем связность в виде функции, которая для данной
