> Source: https://www.ymotongpoo.com/works/goblog-ja/godoc/


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

[Godoc: documenting Go code](https://go.dev/blog/godoc) by Andrew Gerrand

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

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

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

godocはコメントを含むGoのソースコードを解析し、HTMLまたはプレーンテキストとしてドキュメントを
生成します。その結果、生成されるドキュメントはドキュメント対象のコードと密接に結び付いたものに
なります。たとえば、godocのWebインターフェースでは、ある関数の
[ドキュメント](https://go.dev/pkg/strings/#HasPrefix)からワンクリックでその
[実装](https://go.dev/src/strings/strings.go?s=11163:11200#L434)に移動できます。

godocは概念的にはPythonの[Docstring](https://www.python.org/dev/peps/pep-0257/)やJavaの
[Javadoc](https://www.oracle.com/java/technologies/javase/javadoc-tool.html)と似ていますが、
その設計はよりシンプルです。godocが読み取るコメントは、Docstringのように言語構文の一部になって
いるわけでも、Javadocのように機械可読な独自の構文を持つ必要があるわけでもありません。godocの
コメントは、単に良いコメントであり、godocが存在しなかったとしても読みたくなるようなコメントです。

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

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

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

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

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

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

パッケージコメントをどのような長さで書くにしても、その
[最初の文](https://go.dev/pkg/go/doc/#Package.Synopsis)がgodocの
[パッケージ一覧](https://go.dev/pkg/)に表示されるということを覚えておいてください。

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

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

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

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

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

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

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

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

By Andrew Gerrand