目次

godocの記法を実例付きでまとめてみました。

godoc記法

Overview

// godocの記法をまとめます
package godocnosusume

上記のように、packageの上に文章を書くとdocのOverviewに表示されます。

overview表示の様子
overview表示の様子

コード

/*
コード:

  func hoge(){
      fmt.Println("hogehoge")
  }
*/
func (p *Person) SetName(name string) {
	p.Name = name
}

上記のように1行あけて、インデントするとコードブロックのようになります。

コードブロック表示の様子
コードブロック表示の様子

型へのコメント

/*
Personは人を表します
*/
type Person struct {
	Name string // 名前
	// 年齢
	// 複数行でもOK
	Age int
}
型コメント表示の様子
型コメント表示の様子

関数・メソッドへのコメント

/*
渡された文字列をPersonのNameに代入します
*/
func (p *Person) SetName(name string) {
	p.Name = name
}
関数・メソッドのコメント表示の様子
関数・メソッドのコメント表示の様子

定数へのコメント

const (
	MinAge = 0 // 最少年齢
)
定数へのコメント表示の様子
定数へのコメント表示の様子

見出し

見出しとして認識されるためには、行はインデントされておらず、空白行によって隣接する段落テキストから離れている必要があります。

/*
# 見出し
*/
package godocnosusume
見出しへのコメント表示の様子
見出しへのコメント表示の様子

リスト

// リスト
//   - リスト1
//   - リスト2
//   - リスト3
func (p *Person) SetName(name string) {
	p.Name = name
}
リストへのコメント表示の様子
リストへのコメント表示の様子

サンプルコード

関数

package hoge

import "fmt"

func SayHoge() {
	fmt.Println("hoge")
}
package hoge_test

import (
	"fmt"
	hoge "example.com/hoge"
)

func ExampleSayHoge() {
	hoge.SayHoge()
	// Output: hoge
}

上記のようにテストファイルに Example関数名 とすると下記のように表示されます。

サンプルコードの表示の様子
サンプルコードの表示の様子
func ExampleSayHoge_fuga() {
	hoge.SayHoge()
	// Output: hoge
}

ほかの場合の例を書きたい場合は上記のように Example関数名_case名とすると下記のように表示されます。

サンプルコードの表示の様子
サンプルコードの表示の様子

メソッド

// Personは人を表します
type Person struct {
	Name string // 名前
	// 年齢
	// 複数行でもOK
	Age int
}

// 渡された文字列をPersonのNameに代入します
func (p *Person) SetName(name string) {
	p.Name = name
}
func ExamplePerson_SetName() {
	person := godocnosusume.Person{}
	person.SetName("太郎")
	fmt.Println(person.Name)
	// Output: 太郎
}

上記のようにテストファイルに Example型名_関数名 とすると下記のように表示されます。

サンプルコードの表示の様子
サンプルコードの表示の様子

メソッドも関数同様 Example型名_関数名_case名 とすると複数のサンプルコードを載せることができます。


リンク

// [ブログへのリンク]をクリックすると筆者のブログへ飛べます
//
// [ブログへのリンク]: https://yaserarenai.dev

上記のように、文中などリンクを表示したい場所に、 [リンクテキスト] というように記載し。 その後、一行改行して [リンクテキスト]: URLとすると下記のようにリンクを設置できます。

リンクの表示の様子
リンクの表示の様子

URLのあとに文章などが続く場合は、改行してもう1行あけてあげないとしっかりリンクにならないので注意してください。


ドキュメントリンク

同一パッケージ内へのリンク

// [Person] 型や関数などに飛ぶ場合
// [Person.SetName] メソッドなどに飛ぶ場合
ドキュメントリンクの表示の様子
ドキュメントリンクの表示の様子

最後に

せっかく作ったパッケージをもっといろんな人に使ってもらったり、contributeしてもらうためにも、(そしてすべてを忘れてしまった未来の自分のためにも)ドキュメントを書いていきたいですね。

参考文献

Go Doc Comments