8月2日にGo 1.19がリリースされました。Go 1.18ではGenericsを始め、大きな変更点がありましたが、Go 1.19では細かな変更が多くなっています。
今回はGo 1.19の内容で気になったGoDocの機能追加について紹介します。
Go 1.19のリリースノートはこちらです。
Go1.18までのGoDocは、段落やURLをリンクにするなど、非常にシンプルな機能しかありませんでした。
Go1.19では主に、
などが追加され、よりリッチな表現ができるようになりました。
それでは実際にこれらを使ってドキュメントを書いてみます。
セクションタイトルを使うと、文字サイズが大きくなり、アンカーリンクを設置することができます。
セクションタイトルの書き方は、#記号+半角スペース+テキスト
となっています。また、セクションタイトルは連続して書くことができません。
// パッケージ情報 package greeting import "fmt" // セクションタイトルのサンプル // // # セクションタイトル1 // // なにか説明… // // # セクションタイトル2 // // なにか説明… // // # これはだめ // # これはだめ // // ## これもだめ // // 終了 func SayHello (name string) { fmt.Println("Hello "+name+"!") }
ブラウザで表示すると以下のようになります。
リンクを修飾することができるようになりました。書式は以下の通りです。
[リンク名]: アドレス
ここで定義した[リンク名]
をドキュメント内に埋め込むことで、リンクを含めることができます。
また、[パッケージ名]
とすることで、ドキュメント内の別パッケージなどにリンクすることもできます。
// パッケージ情報 package greeting import "fmt" // リンクのサンプル // // リンク1 // “[Link No.1].” // // [リンク2]はこちら // // [io.EOF] 外部パッケージへの参照 // // [Link No.1]: https://hoge.com/link1 // [リンク2]: https://hoge.com/link2 func SayHello (name string) { fmt.Println("Hello "+name+"!") }
ブラウザで表示すると以下のようになります。
リストでは番号なしのリストと番号つきのリストを表現できます。
番号なしのリストの記述は、-+半角スペース+テキスト
です。同様に、番号付きのリストの記述は、数字+.+半角スペース+テキスト
です。
ただし、以下の制約があります。
// パッケージ情報 package greeting import "fmt" // リストのサンプル // // リスト1 // - 項目1 // - 項目12(リストにインデントはできない) // - 項目2 // - 項目3 // // リスト2 // 1. 項目1 // - 項目12(リストにインデントはできない) // 2. 項目2 // 3. 項目3 // 4. 項目4 func SayHello (name string) { fmt.Println("Hello "+name+"!") }
ブラウザで表示すると以下のようになります。
また、go/doc/comment
という新しいパッケージが追加されました。このパッケージはコメントの解析と再フォーマット、そして HTML、Markdown、テキストへのレンダリングのサポートを提供します。
自作したパッケージをGoDocで表示するには、$GOROOT/src
ディレクトリに含める必要があります。しかし、パッケージのコードがこのディレクトリにあると不便なので、下記のようにシンボリックリンクを作成して対応しました。
% ln -s path/to/your/package $GOROOT/src/packagename
Go 1.19でのGoDocの変更点について紹介しました。