Goブログ
Godoc: Goコードのドキュメント化
[注、2022年6月: Goコードのドキュメント化に関する更新されたガイドラインについては、「Goドキュメントコメント」を参照してください。]
Goプロジェクトはドキュメントを真剣に考えています。ドキュメントは、ソフトウェアをアクセス可能で保守可能にする上で非常に重要な部分です。もちろん、適切に記述され、正確でなければなりませんが、記述および保守が簡単である必要もあります。理想的には、ドキュメントはコード自体と結合されるため、ドキュメントはコードとともに進化する必要があります。プログラマーが優れたドキュメントを作成するのが簡単であればあるほど、誰にとってもより良いです。
そのために、godocドキュメントツールを開発しました。この記事では、godocのドキュメントへのアプローチについて説明し、独自のプロジェクトで優れたドキュメントを作成するために、当社の規約とツールをどのように使用できるかを説明します。
Godocは、コメントを含むGoソースコードを解析し、HTMLまたはプレーンテキストとしてドキュメントを生成します。最終的な結果は、ドキュメント化するコードと密接に結合されたドキュメントです。たとえば、godocのWebインターフェイスを介して、関数のドキュメントから、ワンクリックでその実装に移動できます。
Godocは、概念的にはPythonのDocstringやJavaのJavadocに関連していますが、設計はよりシンプルです。godocが読み取るコメントは、(Docstringのように)言語構造ではなく、(Javadocのように)独自のマシン可読構文を持つ必要もありません。Godocのコメントは、godocが存在しなくても読みたいと思うような、単なる優れたコメントです。
規約は単純です。型、変数、定数、関数、さらにはパッケージをドキュメント化するには、その宣言の直前に、間に空白行を入れずに、通常のコメントを記述します。Godocは、そのコメントをドキュメント化する項目の横にテキストとして表示します。たとえば、これはfmtパッケージのFprint関数のドキュメントです。
// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {
このコメントは、記述する要素の名前で始まる完全な文であることに注意してください。この重要な規約により、プレーンテキストからHTML、UNIX manページまで、さまざまな形式でドキュメントを生成でき、最初の行または文を抽出するなど、ツールが簡潔にするために切り詰めた場合に読みやすくなります。
パッケージ宣言に関するコメントは、一般的なパッケージドキュメントを提供する必要があります。これらのコメントは、sortパッケージの簡単な説明のように短くすることができます。
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort
gobパッケージの概要のように詳細にすることもできます。そのパッケージでは、大量の入門ドキュメントが必要なパッケージに対して別の規約を使用します。パッケージコメントは、コメントとパッケージ句のみを含む独自のファイルdoc.goに配置されます。
任意のサイズのパッケージコメントを記述する場合は、その最初の文がgodocのパッケージリストに表示されることに注意してください。
最上位の宣言に隣接していないコメントは、godocの出力から省略されます。ただし、1つの注目すべき例外があります。"BUG(who)”という単語で始まる最上位のコメントは、既知のバグとして認識され、パッケージドキュメントの「バグ」セクションに含まれます。「who」の部分は、詳細情報を提供できるユーザーの名前である必要があります。たとえば、これはbytesパッケージからの既知の問題です。
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
構造体フィールド、関数、型、さらにはパッケージ全体が冗長または不要になる場合がありますが、既存のプログラムとの互換性を保つために保持する必要があります。識別子を使用すべきでないことを示すには、「Deprecated:」で始まり、廃止に関する情報をいくつか記述した段落をドキュメントコメントに追加します。
コメントをHTMLに変換するときに、Godocが使用するいくつかのフォーマットルールがあります。
-
後続のテキスト行は同じ段落の一部と見なされます。段落を区切るには、空白行を残す必要があります。
-
事前にフォーマットされたテキストは、周囲のコメントテキストに対してインデントする必要があります(例については、gobのdoc.goを参照してください)。
-
URLはHTMLリンクに変換されます。特別なマークアップは必要ありません。
これらの規則のいずれも、通常と異なることを行う必要がないことに注意してください。
実際、godocの最小限のアプローチの最大の利点は、その使いやすさです。その結果、標準ライブラリを含む多くのGoコードは、すでに規約に従っています。
上記のコメントがあるだけで、独自のコードで優れたドキュメントを作成できます。$GOROOT/src/pkg内にインストールされているGoパッケージとGOPATHワークスペースは、godocのコマンドラインおよびHTTPインターフェイスを介してすでにアクセス可能であり、-pathフラグを使用するか、ソースディレクトリで"godoc ."を実行するだけで、インデックス作成用の追加パスを指定できます。詳細については、godocドキュメントを参照してください。