godoc で Go のドキュメントを生成する

Java には JavaDoc, JavaScript には JSDoc がありますが、
Go には公式のドキュメント生成ツールとして godoc があります。

    Godoc: documenting Go code
    http://golang.org/doc/articles/godoc_documenting_go_code.html 

GAE の SDK for Go を入れていればそのまま使えます。

$ godoc -html ./model > model.html

出力された HTML は下の写真です。

しかし、このままではスタイルや JavaScript が参照されていません。
デフォルトの HTML テンプレート内で CSS や JS を参照していないためです。

テンプレートはSDK 内の goroot/lib/godoc/godoc.html が使われます。
CSS と JS は以下にあります。

    goroot/doc/style.css
    goroot/doc/godoc.js 

テンプレートのHTMLからこれらのファイルを参照すると、
公式サイトと同じデザインになります。
あとは、必要に応じてスタイルを編集すれば OK です。

私の場合は、 <frameset> を使ってこんな感じのテンプレートを作りました。

godoc はファイルの先頭部分や、関数名の直前に書かれたコメントを拾ってくれます。
/* */ ではなく // を使うのが一般的なようです。

ついでに、godoc を生成するシェルスクリプトを書いておき、
コミット前に実行すると常に最新のドキュメントがプログラムに同梱できて便利です。

godoc.sh

#!/bin/sh
godoc -html ./server > ./document/server/server.html
godoc -html ./server/config > ./document/server/config.html
godoc -html ./server/controller > ./document/server/controller.html
godoc -html ./server/model > ./document/server/model.html
godoc -html ./server/view > ./document/server/view.html
godoc -html ./server/lib > ./document/server/lib.html

実行

$ sh godoc.sh

ちなみに、godoc とは別に GitHub のリポジトリの URL を貼り付けると、
自動的にドキュメントを生成してくれる Web サービスなどもあるようです。
自分でテンプレートを作るのが面倒なときはこっちのほうがいいかも。

   GoDoc
   http://godoc.org