Zenn
📑

godocの記法まとめ

2023/01/20に公開
Go
Go
doc
godoc
tech

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

Overview

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

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

コード

/*
コード:

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

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

型へのコメント

/*
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

リスト

// リスト
//   - リスト１
//   - リスト２
//   - リスト３
func (p *Person) SetName(name string) {
	p.Name = name
}

サンプルコード

関数

hoge.go
package hoge

import "fmt"

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

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

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

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

hoge_test.go
func ExampleSayHoge_fuga() {
	hoge.SayHoge()
	// Output: hoge
}

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

メソッド

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

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

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

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

リンク

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

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

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

ドキュメント リンク

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

// [Person] 型や関数などに飛ぶ場合
// [Person.SetName] メソッドなどに飛ぶ場合

最後に

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

参考文献

Go Doc Comments

Discussion