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)
|
カテゴリ
新型コロナウイルス 主インデックス Haskell 記事リスト 圏論記事リスト 考えるということのリスト 考えるということ ラッセルのパラドックス Haskell Prelude Ocaml ボーカロイド 圏論 jQuery デモ HTML Python ツールボックス XAMPP Ruby ubuntu WordPress 脳の話 話のネタ リンク 幸福論 キリスト教 心の話 メモ 電子カルテ Dojo JavaScript C# NetWalker ed と sed HTML Raspberry Pi C 言語 命題論理 以前の記事
最新のトラックバック
最新のコメント
ファン
記事ランキング
ブログジャンル
画像一覧
|
ファン申請 |
||