The Go Blog

Godoc: Goコードの文書化

Andrew Gerrand
2011年3月31日

[注記、2022年6月：Goコードの文書化に関する最新のガイドラインについては、「Go Doc Comments」を参照してください。]

Goプロジェクトはドキュメンテーションを真剣に考えています。ドキュメンテーションは、ソフトウェアをアクセスしやすく、保守しやすくするために非常に重要です。もちろん、適切に書かれ、正確である必要がありますが、書きやすく、保守しやすいものでなければなりません。理想的には、ドキュメンテーションがコード自体と連携し、コードの進化とともにドキュメンテーションも進化するようにすべきです。プログラマーが良いドキュメンテーションを作成しやすければ、誰もにとってより良い結果をもたらします。

この目的のために、私たちはgodocドキュメンテーションツールを開発しました。この記事では、godocのドキュメンテーションへのアプローチについて説明し、皆さんが自身のプロジェクトで良いドキュメンテーションを作成するために、私たちの慣習とツールをどのように使用できるかを説明します。

GodocはGoのソースコード（コメントを含む）を解析し、HTMLまたはプレーンテキストとしてドキュメンテーションを生成します。その結果、ドキュメンテーションは、それが文書化するコードと密接に連携します。例えば、godocのウェブインターフェースを通じて、関数のドキュメンテーションからその実装へワンクリックで移動できます。

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)”という単語で始まるトップレベルのコメントは既知のバグとして認識され、パッケージドキュメンテーションの「Bugs」セクションに含まれます。「who」の部分は、より詳しい情報を提供できる人物のユーザー名であるべきです。例えば、これはbytesパッケージからの既知の問題です

// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.

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

GodocがコメントをHTMLに変換する際に使用するいくつかの書式設定ルールがあります。

  • テキストの次の行は同じ段落の一部と見なされます。段落を区切るには空白行を挟む必要があります。

  • 整形済みテキストは、周囲のコメントテキストに対してインデントする必要があります（例については、gobのdoc.goを参照）。

  • URLはHTMLリンクに変換されます。特別なマークアップは不要です。

これらのルールのどれも、通常とは異なることを要求しないことに注意してください。

実際、godocの最小限のアプローチの最も良い点は、その使いやすさです。その結果、標準ライブラリのすべてを含む多くのGoコードが、すでにこれらの慣習に従っています。

あなたのコードも、上記のコメントを持つだけで良いドキュメンテーションを提供できます。$GOROOT/src/pkg内にインストールされたGoパッケージや、任意のGOPATHワークスペースは、godocのコマンドラインおよびHTTPインターフェースを通じてすでにアクセス可能であり、-pathフラグを使用するか、ソースディレクトリで"godoc ."を実行するだけで、インデックス作成用の追加パスを指定できます。詳細については、godocドキュメンテーションを参照してください。

次の記事：Gofixの紹介
前の記事：Gobs of data
ブログインデックス

go.dev は、サービスの品質を提供および向上させ、トラフィックを分析するために、Google の Cookie を使用しています。詳細はこちらをご覧ください。