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 宣言の一部分へのコメント

・クラスメソッド トップレベル宣言に同じ（「-- |」 や「-- ^」を使う）。

例

class C a where
  -- | This is the documentation for the 'f' method
  f :: a -> Int
  -- | This is the documentation for the 'g' method
  g :: Int -> a

・コンストラクタ，レコードフィールド　同上

例

data T a b 
  -- | This is the documentation for the 'C1' constructor
  = C1 a b
  -- | This is the documentation for the 'C2' constructor
  | C2 a b

あるいは

data T a b 
  = C1   -- ^ This is the documentation for the 'C1' constructor
      a  -- ^ This is the documentation for the argument of type 'a'
      b  -- ^ This is the documentation for the argument of type 'b'

data R a b = 
  C { -- | This is the documentation for the 'a' field
      a :: a,
      -- | This is the documentation for the 'b' field
      b :: b
    }

data R a b = 
  C { a :: a -- ^ This is the documentation for the 'a' field
    , b :: b -- ^ This is the documentation for the 'b' field
    } 

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@.
-}
module W where
...

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

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

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

3 ドキュメントの構造

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

3-1 セクション頭書

• 自動で目次が作られる。
• Class, Typeなどは同位のセクション，Type, A data type などはセクションの下位化
• 「-- *」，「-- **」などで書き始める。*数はセクションの下位化

例

module Foo (
  -- * Classes
  C(..),
  -- * Types
  -- ** A data type
  T,
  -- ** A record
  R,
  -- * Some functions
  f, g
  ) where

上記のようにモジュール宣言に続く輸出リストを使わない場合，モジュール本体側にセクションの見出しを入れることになる。

module Foo where

-- * Classes
class C a where ...

-- * Types
-- ** A data type
data T = ...

-- ** A record
data R = ...

-- * Some functions
f :: ...
f = ...
g :: ...
g = ...

3-2 名前付きの記述の塊

・「-- $XXX」以降の記述は別の「-- $XXX」から参照される。（XXXは名前）

例

module Foo (
  -- * A section heading

  -- $doc
) where

-- $doc
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.

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

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

モジュール属性

Haddock用のモジュール属性の記述は，冒頭にコンマ区切りで記述する。

例

{-# OPTIONS_HADDOCK hide, prune, ignore-exports #-}
-- Module description
module A where
...

モジュールのHaddock属性の例：

• hide 該当モジュールの文書を作成しないが，外部に輸出している定義に関する記述は外部モジュールで利用可能
• prune 記述のない定義は無視する
• ignore-exports 輸出リストを無視する輸出リストを無視する。
• not-home
• show-extensions

例

’>>>'を使えば，REPLを使用している際に表示される例の記述が可能である。

-- | Two examples are given below:
--
-- >>> fib 10
-- 55
--
-- >>> putStrLn "foo\nbar"
-- foo
-- bar

ブロックエディタでの編集に切り替え。ちょっと更新追記。 実は原文はまだまだ記載が続くが，未翻訳。 2021.01.24