ドキュメント総まとめ（go doc/pkg.go.dev）

Goはソースコードのコメントを解析し、ドキュメントを生成する仕組みが備わっています。

ここでは主に次の内容を説明をします。

ドキュメントに掲載するコメントの書き方
CLI（go doc）によるドキュメントの参照
Web（pkg.go.dev）によるドキュメントの参照・公開

コメントの書き方

コメントの書き方は非常にシンプルです。宣言（パッケージ・型・変数・定数・関数など）の直前に通常のコメントを書くだけです。

これはパッケージと関数にドキュメントを記載したサンプルです。

// ここにパッケージの説明を書きます。
package os

// ここに関数の説明を書きます。
func MkDir(name string) { /* 処理は省略 */ }

空行を空けずに書く必要があります。

// これはNGです。

package os

コメントからHTMLへの変換規則

コメントがHTMLに変換される際の規則は次の通りです。

段落は空行のコメントで区切られる
大文字で始まり、カンマを除く句読点がない単一行の段落は、見出しになる（英語向け）
インデントを入れると整形済みテキストになる（HTMLのpreタグ）
URLは自動的にリンクになる

// MkDirは新規ディレクトリを作成します。
//
// これは新しい段落です。
//
//     // これは整形済みテキストです。
//     MkDir("test")
func MkDir(name string) { /* 処理は省略 */ }

サンプルコードの追加

標準パッケージのドキュメントの中にはサンプルコードがあります（例：fmt.Println）。

サンプルコードは『コメント』ではなく『サンプル用のテストコード』を書くことで、ドキュメントに反映されます。こうすることで正常に動作するサンプルコードを素早く提供できます。

詳しくはテストのページを参照してください。

ドキュメントの参照（CLI）

go docコマンドによりドキュメントを参照できます。

手元で開発中のパッケージは、パッケージのディレクトリまで移動して、次のコマンドで参照できます。

# 現在のディレクトリのパッケージを参照
go doc
# 現在のディレクトリのパッケージのMkDirを参照
go doc MkDir

標準パッケージやサードパーティパッケージは、次のコマンドで参照できます。

# fmtパッケージを参照
go doc fmt
# fmtパッケージのPrintln関数を参照
go doc fmt.Println
# html/templateパッケージのNew関数を参照
go doc html/template.New
# html/templateパッケージのTemplate型のExecuteメソッドを参照
go doc html/template.Template.Execute
# サードパーティパッケージを参照
# ※参照するには事前のダウンロードが必要
go doc github.com/google/go-cmp/cmp

パッケージのすべてのドキュメントを参照するには、-allオプションを指定します。

# fmtパッケージの全てのドキュメントを参照
go doc -all fmt

ドキュメントの参照（Web）

Goのモジュールやパッケージのドキュメントはhttps://pkg.go.dev/に公開されています。標準ライブラリからサードパーティまで一元管理されています。

pkg.go.devは2019年から公開されたもので、それ以前はgodoc.orgに公開されていました。インターネット上の古い記事ではgodoc.orgをリンクしているものがありますので注意してください。

ドキュメントの公開（Web）

Go Modulesを公開すると、ドキュメントは自動でhttps://pkg.go.dev/に公開されます。

公開されない場合はhttps://go.dev/about#adding-a-packageを参照してください。