Goメモ-476 (ドキュメントコメントを扱う)(go/doc/commentパッケージ)

関連記事

GitHub - devlights/blog-summary: ブログ「いろいろ備忘録日記」のまとめ

概要

以下、自分用のメモです。忘れないうちにメモメモ。。。

知らなかったのですが、go/doc/comment というパッケージがあるのですね。

Goのドキュメントコメント形式の文字列を解釈して、いろいろな形式に変換してくれるパッケージです。

面白そうだったので、少し試してみました。

サンプル

package main

import (
    "flag"
    "go/doc/comment"
    "log"
    "os"
)

const (
    sample = `
# Title

helloworld.

[path/filepath] package.

[io.Reader] interface.

code block
        package main
        func main(){}

list
        - a
        - b

[path/filepath]: https://pkg.go.dev/path/filepath@go1.23.1
[io.Reader]: https://pkg.go.dev/io@go1.23.1#Reader
`
)

type (
    Args struct {
        markdown bool
        html     bool
        comment  bool
        text     bool
    }
)

var (
    args Args
)

func init() {
    flag.BoolVar(&args.markdown, "md", false, "output markdown")
    flag.BoolVar(&args.html, "html", false, "output html")
    flag.BoolVar(&args.comment, "comment", false, "output go comment")
    flag.BoolVar(&args.text, "text", false, "output text")
}

func main() {
    log.SetFlags(0)
    flag.Parse()

    if err := run(); err != nil {
        log.Panic(err)
    }
}

func run() error {
    var (
        parser  comment.Parser
        printer comment.Printer
        doc     *comment.Doc
        buf     []byte
    )
    doc = parser.Parse(sample)
    printer.TextPrefix = "// "

    switch {
    case args.markdown:
        buf = printer.Markdown(doc)
    case args.html:
        buf = printer.HTML(doc)
    case args.comment:
        buf = printer.Comment(doc)
    case args.text:
        buf = printer.Text(doc)
    default:
        flag.PrintDefaults()
        return nil
    }

    if _, err := os.Stdout.Write(buf); err != nil {
        return err
    }

    return nil
}

実行すると以下のように出力されます。

$ task
task: [build] go build -o app .
task: [run] ./app -h
Usage of ./app:
  -comment
        output go comment
  -html
        output html
  -md
        output markdown
  -text
        output text
task: [run] ./app -md
### Title {#hdr-Title}

helloworld.

[path/filepath](https://pkg.go.dev/path/filepath@go1.23.1) package.

[io.Reader](https://pkg.go.dev/io@go1.23.1#Reader) interface.

code block

        package main
        func main(){}

list

  - a
  - b
task: [run] ./app -html
<h3 id="hdr-Title">Title</h3>
<p>helloworld.
<p><a href="https://pkg.go.dev/path/filepath@go1.23.1">path/filepath</a> package.
<p><a href="https://pkg.go.dev/io@go1.23.1#Reader">io.Reader</a> interface.
<p>code block
<pre>package main
func main(){}
</pre>
<p>list
<ul>
<li>a
<li>b
</ul>
task: [run] ./app -comment
# Title

helloworld.

[path/filepath] package.

[io.Reader] interface.

code block

        package main
        func main(){}

list
  - a
  - b

[path/filepath]: https://pkg.go.dev/path/filepath@go1.23.1
[io.Reader]: https://pkg.go.dev/io@go1.23.1#Reader
task: [run] ./app -text
// # Title
//
// helloworld.
//
// path/filepath package.
//
// io.Reader interface.
//
// code block
//
//      package main
//      func main(){}
//
// list
//   - a
//   - b

[path/filepath]: https://pkg.go.dev/path/filepath@go1.23.1
[io.Reader]: https://pkg.go.dev/io@go1.23.1#Reader

try-golang/examples/singleapp/doc_comment at main · devlights/try-golang · GitHub

参考情報

Goのおすすめ書籍

初めてのGo言語 ―他言語プログラマーのためのイディオマティックGo実践ガイド

実用 Go言語 ―システム開発の現場で知っておきたいアドバイス

Go言語による並行処理

Go言語 100Tips ありがちなミスを把握し、実装を最適化する impress top gearシリーズ

Goならわかるシステムプログラミング 第2版

効率的なGo ―データ指向によるGoアプリケーションの性能最適化

---

過去の記事については、以下のページからご参照下さい。

• ブログ 「いろいろ備忘録日記」の記事まとめ | ブログ「いろいろ備忘録日記」のまとめ

サンプルコードは、以下の場所で公開しています。

• GitHub - devlights/try-golang: This is my TUTORIAL project for golang.
• GitHub - devlights/try-python: This is my TUTORIAL project for Python.
• GitHub - devlights/try-csharp: This is my TUTORIAL project for C#.