人気ブログランキング | 話題のタグを見る

System.Random (5) Haddock

Haddock User Guid の Chapter 3. Documentation and Markup (文書の仕様とマークアップ)

この章では、Haddock 文書を作成するときの説明文書の作り方や、マークアップの方法を延べてある。System.Random モジュールのソース解読が目的なので、ここでは、System.Random を解読できる程度の要素をピックアップする。

3.1. Documenting a top-level declaration

このセクションでは、top-level の宣言(関数のタイプの宣言や、型の宣言、型クラスの宣言など)につける注釈の記入の仕方を説明してある。この注釈は、Haddock では基本的なもので頻出する。例えば、

square :: Int -> Int
square x = x * x

という関数が宣言されていた時、これに対する説明は、Haskell のコメント記号 -- のあとに | をつけて、次のように記入する。

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

実際の例として、Hackage の System.Random のHTML 文書をそのソースコードと比較してみる。

System.Random のソースコードを読むと、class RandomGen g where という RandomGen 型クラスの宣言の上に -- | の後に RandomGen クラスの注釈が書いてあるが、

-- | The class 'RandomGen' provides a common interface to random number
-- generators.
--
-- Minimal complete definition: 'next' and 'split'.

class RandomGen g where

これを Hackage の System.Random の Haddock 文書で見ると次のように記述されている。

class RandomGen g whereSource

    The class RandomGen provides a common interface to random number generators.

    Minimal complete definition: next and split.

Hackage の System.Random の文書とそのソースコードを比べてみると、この注釈と宣言の関係が数多く見られるのがわかる。この Haskell の entity に注釈をつけるやり方が Haddock の基本であることが分かる。したがって、-- コメントの記述のみの場合は、このコメントは Haddock 文書に反映されず隠蔽できる。

-- | は宣言文の前にコメントを置く場合に使用されるが、--^ はコメントを宣言文の後に記述する場合に -- | と同じ意味を持たせることができる。しかし、ここでは詳細は省略する。

3.2. Documenting parts of a declaration

この節では、クラスメソッドや、コンストラクタとそのフィールド、関数の引数などに Haddock のコメントを付ける方法が説明されているが、基本的には上の例と同じ意味であるので説明を省略する。

3.3. The module description

ここでは、モジュール全体についての説明の書き方を説明してある。モジュール全体については、Module, Description, Copyright, License, Maintainer, Stability, Portability などのどのモジュールにも共通のキーワードがあるので、Haddock ではそれを抽出して特別に表示する。

この注釈はソースコードの冒頭に置かれている。

System.Random の冒頭は次のようになっているが、

-----------------------------------------------------------------------------
-- |
-- Module      :  System.Random
-- Copyright   :  (c) The University of Glasgow 2001
-- License     :  BSD-style (see the file libraries/base/LICENSE)
--
-- Maintainer  :  libraries@haskell.org
-- Stability   :  stable
-- Portability :  portable
--
-- This library deals with the common task of pseudo-random number
-- generation. The library makes it possible to generate repeatable
-- results, by starting with a specified initial random number generator,
-- or to get different results on each run by using the system-initialised
-- generator or by supplying a seed from some other source.
--
-- The library is split into two layers:
--
-- * A core /random number generator/ provides a supply of bits.
--   The class 'RandomGen' provides a common interface to such generators.
--   The library provides one instance of 'RandomGen', the abstract
--   data type 'StdGen'.  Programmers may, of course, supply their own
--   instances of 'RandomGen'.
--
-- * The class 'Random' provides a way to extract values of a particular
--   type from a random number generator.  For example, the 'Float'
--   instance of 'Random' allows one to generate random values of type
--   'Float'.
--
-- This implementation uses the Portable Combined Generator of L'Ecuyer
-- ["System.Random\#LEcuyer"] for 32-bit computers, transliterated by
-- Lennart Augustsson.  It has a period of roughly 2.30584e18.
--
-----------------------------------------------------------------------------

Hackage の System.Random 文書の右上の部分を見ると、キーワードの内容が抽出されて、それぞれ表示されているのが分かる。注釈の先頭の行の冒頭にある -- | に注目して欲しい。Haddock 文書に反映される注釈は全て -- | で始まることが分かる。

こうしてみると、Hackage の Haskell のモジュールについての文書の内容が、モジュールのソースコードに密着しているのがわかる。また、HTML 文書からソースコードへはハイパーリンクで簡単にアクセスできるので、Haskell のモジュールのソースコードの解読は、Hackage の Haddock 文書からスタートすれば十分であることが分かる。
by tnomura9 | 2015-01-12 15:06 | Haskell | Comments(0)
<< System.Random (... System.Random (... >>