Haddock を使ってみる

Haskell 界のデファクトスタンダードなドキュメント生成ツール Haddock を使ってみる。とりあえず関数の説明とか、引数の説明とか、データ型の説明あたりの、当たり前のことができるようになれれば満足。

Haddock User Guide を参照した。

module Main where

-- トップレベルの宣言に対するドキュメントは '-- |' で始める. ドキュメン
-- ト対象の宣言前にコメントをつけるだけなら, これだけ覚えとけば OK.

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

-- ドキュメントコメントの行は複数になってもいい.

-- | class X.
-- This is the sample of the multi line documentation.
class X a where
    -- メソッドは関数と同じ感じでドキュメントできる.生成されるドキュメン
    -- トでの段落を分けたい場合には, 空のコメント行を間に挟む.
    -- 宣言の後にドキュメントコメントをつけたい場合 (引数の説明を付けた
    -- いとか) の場合には, '-- ^' を使う.

    -- | The class method 'f' returns Int.
    --
    -- paragraph.
    f :: a -- ^ The object of instanced type.
      -> Int -- ^ The result.

-- データ型. これも大体で今までと同じ. コンストラクタ, フィールドにもド
-- キュメントをつけられる.

-- | This is the documentation for the T
data T a
    -- | C1.
    = C1 a
    | C2 { x :: a   -- ^ this is the documentation for the 'x' field
         , y :: Int -- ^ this is the documentation for the 'y' field
         }

-- インスタンス宣言にはどうも無理っぽかった.

-- | This is the documentation for definition instantiation?
instance X (T a) where
    f (C1 _) = 1
    f (C2 _ x) = x

main = print "hello"

関数、クラス、データ型の概要には前コメントを、引数の説明、コンストラクタの説明などには後コメントを使うと読みやすそうな感じがする。

ドキュメントコメントに日本語を含めてみたが、案の定出力されなかった。ブラウザでの表示は空白、Vim で HTML ファイルを開いてみると、^B となっていた。

ざっと調べてみると http://behind-the-expression.blogspot.com/2008/07/haddock.html という記事があった。この記事によれば非 ASCII 文字はエスケープして出力されるはずだが、そうはならなかった。記事の Haddock はバージョン 0.8 で、うちのは 2.3。この辺の違いか？