Haskellメモ Haddock

この説明は,Haskellの公式サイトの記述を魚野が自分のメモとして部分的に日本語化したもの。
詳細は下記サイト参照。
http://haskell-haddock.readthedocs.io/en/latest/markup.html

1 Haddockとは

Haddockとは,プログラミング言語,Haskellのソースファイルにコメントを記述することで,
自動的に参考用の文書を作成するシステムのこと。

2 Haddockの記法

2-1 トップレベル宣言

・トップレベル(関数の型署名や方宣言,クラス宣言等)での記述。
・「--|」という句で書き出すと,それ以降の部分はその直後の宣言に関する説明となる。

-- | The 'square' function square an integer
square :: Int -> Int
square x = x * x

・トップレベルとは
トップレベルの関数の型署名
型署名のないトップレベルの関数の定義
data 宣言
newtype 宣言
type 宣言
class 宣言
data family または type family 宣言
data instance またはtype instance 宣言
・別の宣言が続いた時は,後の宣言はHaddockに無視される。
・宣言の後にコメントを書くことも可能。

square :: Int -> Int
-- ^ The 'square' function square an integer
square x = x * x

2-2 宣言の一部分へのコメント

・クラスメソッド トップレベル宣言に同じ(「-- |」 や「--^」を使う)。
・コンストラクタ,レコードフィールド 同上

2-3 関数の引数

・「--^」を使う。

f :: Int -- ^ The 'Int' argument
-> Float -- ^ the 'Float' argument
-> IO() -- ^ the return value

2-4 モジュールの説明

・モジュールの説明は記述が多岐にわたることが多い。

{-|
Module : W
Description : Short description
Copyright : (c) Some Guy, 2013
Someone Else, 2014
License : GPL-3
Maintainer : sample@email.com
Stability : experimental
Portability : POSIX

Here is a longer description of this module, containing some
commentary with @some markup@.
-}

・各フィールド全てを記述する必要はない。重要度の順で記述すること。
・各フィールドの中身が二行以上になる時は,フィールドのラベル終了位置よりも右方から記述する。
・但し,冒頭に「--」を記述した際は例外(詳細は冒頭のURL参照)

2−5 モジュールの説明要素

・Module モジュール名
・Description モジュールの概説。
・Copyright, License, Maintainer, Stability できるだけ明示すること
・Portability OSの制約や必要なGHC拡張が記述されることが多い。

3 ドキュメントの構造

・各モジュールが輸出(エクスポート)している要素のみ説明文作成の対象とされる。
・輸入(インポート)されたモジュールで輸出されている場合も説明文作成の対象となる。
・3つの構造がある:セクション頭書,名前付記述,モジュール全体の再輸出

3-1 セクション頭書

・Class, Typeなどは同位のセクション,Type, A data type などはセクションの下位化
・「-- *」,「-- **」などで書き始める。*数はセクションの下位化

3-2 名前付記述

・名前付記述 二個目の「-- $XXX」以降の記述は一個めの「-- $XXX」の部分に置かれる。
XXXは名前)

3-3 ハイパーリンクと要素再輸出

・Haddockは説明文書作成の際,クラス名などを全てハイパーリンクつきにする。