Go言語でモジュールを作成し、GoDocを使ってドキュメントを作成する

はじめに

Go言語についてと開発環境の準備 でGo言語についてと開発環境の方法を学びました。

Go言語でモジュールを作成し、GoDocを使ってドキュメントを作成する方法について備忘録としてまとめました。

GoDocとは

GoDocはルールに沿ってソースコードにコメントを記述することで、パブリックな関数、type、変数についての説明や実装例をドキュメントとしてホストしているウェブサイトにまとめてくれます。また、コマンドライン上でもドキュメントを閲覧することが出来ます。

参考にしたGo言語学習本

• 基礎からわかる Go言語
• スターティングGo言語
• Go言語によるWebアプリケーション開発
• Goプログラミング実践入門　標準ライブラリでゼロからWebアプリを作る

参考サイト

https://godoc.org/golang.org/x/tools/cmd/godoc
https://blog.golang.org/examples

事前準備

Go言語についてと開発環境の準備 を読んでGo言語の開発環境を準備します。

go getでGoDocのパッケージをインストールします。

$ go get golang.org/x/tools/cmd/godoc

テスト実装

Package stringutil をサンプルに実際にドキュメントを作成してみました。

サンプルコード
https://github.com/golang/example
https://pkg.go.dev/github.com/golang/example/stringutil/

package stringutil_test

import (
    "fmt"

    "github.com/golang/example/stringutil"
)

func ExampleReverse() {
    fmt.Println(stringutil.Reverse("hello"))
    // Output: olleh
}

関数コメントや ExampleReverse で使用例を example_test.go に記述し、テストを実行します。

$ go test -v
=== RUN TestReverse
--- PASS: TestReverse (0.00s)
=== RUN: ExampleReverse
--- PASS: ExampleReverse (0.00s)
PASS
ok  	github.com/golang/example/stringutil	0.009s

ドキュメントをWebページとして表示します。

$ godoc -http =：6060