Godoc: Goコードをドキュメント化する

Godoc: documenting Go code by Andrew Gerrand

[注、2022年6月: Goコードのドキュメント作成に関する最新のガイドラインについては、「Go Doc Comments」を参照してください。]

Goプロジェクトはドキュメントを重要視しています。ドキュメントは、ソフトウェアを利用しやすく、保守しやすいものにするための大きな要素です。もちろんドキュメントはよく書かれていて正確でなければなりませんが、それと同時に書きやすく保守しやすいものである必要もあります。理想を言えば、ドキュメントはコードそのものと結び付いていて、コードの変化とともに進化していくべきです。プログラマーが優れたドキュメントを書きやすいほど、誰にとっても好都合です。

そのために、私たちはgodocというドキュメントツールを開発しました。この記事ではgodocのドキュメントに対するアプローチを説明し、自分のプロジェクトで優れたドキュメントを書くために、私たちの規約とツールをどのように使えるかを解説します。

godocはコメントを含むGoのソースコードを解析し、HTMLまたはプレーンテキストとしてドキュメントを生成します。その結果、生成されるドキュメントはドキュメント対象のコードと密接に結び付いたものになります。たとえば、godocのWebインターフェースでは、ある関数のドキュメントからワンクリックでその実装に移動できます。

godocは概念的にはPythonのDocstringやJavaの Javadocと似ていますが、その設計はよりシンプルです。godocが読み取るコメントは、Docstringのように言語構文の一部になっているわけでも、Javadocのように機械可読な独自の構文を持つ必要があるわけでもありません。godocのコメントは、単に良いコメントであり、godocが存在しなかったとしても読みたくなるようなコメントです。

規約はシンプルです。型、変数、定数、関数、あるいはパッケージにドキュメントを付けるには、その宣言の直前に、間に空行を挟まずに、普通のコメントを書きます。すると、godocはそのコメントをドキュメント対象の項目とともにテキストとして表示します。たとえば、次はfmtパッケージの Fprint関数のドキュメントです。

// Fprintはオペランドのデフォルトのフォーマットを使って整形し、wに書き込みます。
// オペランドがどちらも文字列でない場合は、間にスペースが追加されます。
// 書き込まれたバイト数と、発生した書き込みエラーを返します。
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {

このコメントが、説明対象の要素の名前で始まる完全な文になっていることに注目してください。この重要な規約のおかげで、プレーンテキストからHTML、UNIXのmanページに至るまで、さまざまな形式でドキュメントを生成できるようになります。また、ツールが最初の1行や1文だけを抜き出して簡潔に表示するような場合にも、読みやすい表示になります。

パッケージ宣言に対するコメントは、パッケージ全体についての一般的なドキュメントを提供するべきです。こうしたコメントは、sortパッケージの簡潔な説明のように、短くても構いません。

// sortパッケージはスライスやユーザー定義のコレクションをソートするための
// プリミティブを提供します。
package sort

また、gobパッケージの概要のように、詳細なコメントにすることもできます。gobパッケージでは、大量の導入的なドキュメントが必要なパッケージ向けの別の慣習を採用しています。それは、パッケージコメントを専用のファイル doc.goに置くというもので、そのファイルにはこのパッケージコメントとpackage節だけが含まれます。

パッケージコメントをどのような長さで書くにしても、その最初の文がgodocのパッケージ一覧に表示されるということを覚えておいてください。

トップレベルの宣言に隣接していないコメントはgodocの出力から除外されますが、一つだけ注目すべき例外があります。"BUG(who)"という単語で始まるトップレベルのコメントは既知のバグとして認識され、パッケージドキュメントの「Bugs」セクションに含まれます。「who」の部分には、より詳しい情報を提供できる人のユーザー名を入れるべきです。たとえば、次は bytesパッケージにある既知の問題です。

// BUG(r): Titleが単語の境界に使うルールは、Unicodeの句読点を正しく扱えません。

構造体のフィールド、関数、型、あるいはパッケージ全体が、冗長になったり不要になったりしても、既存のプログラムとの互換性のために残しておかなければならないことがあります。その識別子を使うべきではないことを示すには、そのdocコメントに「Deprecated:」で始まる段落を追加し、非推奨に関する情報を続けて書きます。

godocがコメントをHTMLに変換する際に使う書式ルールがいくつかあります。

続くテキストの行は同じ段落の一部とみなされます。段落を分けるには空行を入れる必要があります。
整形済みテキストは、周囲のコメントのテキストに対して字下げしなければなりません（例については gobのdoc.goを参照してください）。
URLは自動的にHTMLのリンクに変換されます。特別なマークアップは必要ありません。

これらのルールのどれもが、特別なことをする必要がないということに注意してください。

実のところ、godocのこの最小限のアプローチの一番良いところは、使うのがとても簡単だという点です。その結果、標準ライブラリのすべてを含む多くのGoコードが、すでにこの規約に従っています。

自分のコードも、上で説明したようなコメントを持たせるだけで、優れたドキュメントを提示できます。 $GOROOT/src/pkg内にインストールされたGoパッケージや、GOPATHのワークスペースにあるパッケージは、 godocのコマンドラインインターフェースやHTTPインターフェースからすでにアクセスできます。また、 -pathフラグを使うか、ソースディレクトリで単に"godoc ."を実行することで、インデックス対象に追加のパスを指定できます。詳細についてはgodocのドキュメントを参照してください。

By Andrew Gerrand