HaskellのJavadoc, Haddockを使う

HaskellでJavadocやRDocに相当するドキュメンテーション生成ツールHaddockを使ってみます。

インストール

cabalが便利なのでcabalを使います。
まず、パッケージ情報を更新しておきます。

$ cabal update

古いパッケージをアップグレードしておきたい場合は、

$ cabal install --upgrade-dependencies

とします。では、haddockをインストールしてみます。

$ cabal install haddock
Resolving dependencies...
Downloading haddock-2.13.2.1...
Configuring haddock-2.13.2.1...
cabal: The program alex version >=2.3 is required but the version of
/Users/succzero/.cabal/bin/alex could not be determined.
Failed to install haddock-2.13.2.1
cabal: Error: some packages failed to install:
haddock-2.13.2.1 failed during the configure step. The exception was:
ExitFailure 1

おや、エラーが出ました。どうやらalexのバージョンが古いようです。最新にアップグレードされているはずなのに、なぜ？
alexのバージョンを確認しましょう。

$ alex -v
dyld: Library not loaded: /opt/local/lib/gcc47/libgcc_s.1.dylib
  Referenced from: /Users/succzero/.cabal/bin/alex
  Reason: image not found

実行すらされない:(
そういえば、gcc47を消してgcc48に切り替えていたので、依存ライブラリをロード出来るわけがないのですね。ビルドし直します。
再インストールするときはcabal install --reinstallとします。

$ cabal install --reinstall alex
Resolving dependencies...
Downloading alex-3.1.3...
...
Linking dist/build/alex/alex ...
Installing executable(s) in /Users/succzero/.cabal/bin
Installed alex-3.1.3

ビルドできました。

$ alex -v
Alex version 3.1.3, (c) 2003 Chris Dornan and Simon Marlow

れっつリトライ

$ cabal install haddock

ドキュメントを書いてみる

ドキュメントコメントは、{- | ... } や -- | の形式で記述します。
通常のコメントに対して、コメントの先頭行に|を加えればとりあえずOK。

{- |
Module      : Main
Description : ドキュメンテーションテスト
Copyright   : (c) succzero, 2014
License     : GPL-3
Maintainer  : succzero@gmaill.com
Stability   : experimental
Portability : POSIX

ここにモジュールの詳細な記述を書く．
-}
module Main where

-- | 'Hello, World'を表示する．
main :: IO ()
main = putStrLn "Hello, World"

このソースコードから実際にドキュメントを生成してみます。

$ haddock -h Main.hs -o doc

-hオプションを指定すると、htmlでドキュメントを生成します。-c CSSファイルパスで指定したCSSファイルを適用することも出来ます。
-oオプションは、ドキュメントの生成先ディレクトリを指定します。

生成されたものがこちら。

f:id:succzero:20140225012750p:plain

どうやら日本語がうまく使えないようです。

日本語文字を削除して、他のマークアップも試してみます。

{-# HADDOCK Markdown #-}
{- |
Module      : Main
Description : This is documentation tests.
Copyright   : (c) succzero, 2014
License     : GPL-3
Maintainer  : succzero@gmaill.com
Stability   : experimental
Portability : POSIX

Here is a longer description of this module.
-}
module Main where

-- | Display the string 'Hello, World'.
--
-- __ Bold(strong) __, /Emphasis(italic)/, @Monospace: f x = x + 1@
--
-- Code Blocks:
--
-- @
--     fix f = f (fix f) 
-- @
-- 
--
-- Itemize:
--
--     * foo
--
--     * bar
main :: IO ()
main = putStrLn "Hello, World"