在 pkg.go.dev 上的文档，都是 Go 自动从开源项目的工程代码中爬取、格式化后展现出来的。

每个人都可以写自己的 GoDoc 并且展示在 pkg.go.dev 上，只需要遵从 GoDoc 的格式标准即可，也不需要任何审核动作。

godoc 命令

1. 安装godoc: go get -v golang.org/x/tools/cmd/godoc
2. cd your_mod_project_dir && godoc -http=:6060

以 jsonvalue 为例:

github.com/Andrew-M-C/go.jsonvalue -> http://${IP}:${PORT}/pkg/github.com/Andrew-M-C/go.jsonvalue/

pkgsite 命令

>= Go 1.18

1. 安装：go install golang.org/x/pkgsite/cmd/pkgsite@latest
2. cd your_mod_project_dir && pkgsite -http=:6060

http://${IP}:${PORT}/github.com/Andrew-M-C/go.jsonvalue/

GoDoc语法

// SomeNewLine 只是用来展示如何在 GoDoc 中换行。
//
// 你看，这就是新的一行了，耶～✌️
func SomeNewLine() error {
    return nil
}

• 绑定注释: 使用单行 // 或多行 /* */ 注释符，且紧挨着代码定义上方一行的注释，都会被视为该内容的 GoDoc，从而被提取出来。
• 内嵌代码: 注释行以制表符 \t(按tab键) 开头，或以多于一个空格（包括制表符）开头
• 换行: 插入一行空注释

在注释中如果只是单纯的一个换行另写注释的话，在页面是不会将其当作新的一段来看待的，GoDoc 的逻辑，也仅仅渲染完这一行之后，再加一个空格，然后继续渲染下一行。

Overview 部分

包注释是写在 go 文件最开始的 package xxx 上面。虽然 GoDoc 没有限制、但是 Go 官方建议包注释应当以 // Package xxx 开头作为文本的主语。

如果在一个 package 中，有多个文件都包含了包注释，那么 GoDoc 会按照文件的字典序，依次展示这些文件中的包注释。但这样可能会带来混乱，因此一个 package 我们应当只在一个文件中写包注释。

弃用代码声明

GoDoc 提供了一个关键字 Deprecated:，作为整个注释块的第一个单词

// Deprecated: ElemAt 这个函数弃用，后续请迁移到 IntsElem 函数中.
func ElemAt(ints []int, index int) int {
    // ......
}

代码示例文档

首先，我们应该新建至少一个文件，专门用来存放示例代码。比如我就把示例代码写在了 example_jsonvalue_test.go 文件中。这个文件的 package 名不得与当前包名相同，而应该命名为 包名_test 的格式。

此外，需要注意的是，示例代码文件也属于单元测试文件的内容，当执行 go test 的时候，示例文件也会纳入测试逻辑中。

func ExampleSet_At_1() {
    ......
}

• Example 这是示例代码的固有开头
• Set 表示这是类型 Set 的示例
• 第一个下划线 _ 分隔符: 在这个分隔符后面的，是 Set 类型的成员函数名
• At 表示这是函数 At() 的示例，搭配前面的内容，则表示这是类型 Set 的成员函数 At() 的示例
• 第二个下划线 _ 分隔符: 在这个分隔符后面的内容，是示例代码的额外说明
• 1 这是示例代码的额外说明，也就是前面 “Example (1)” 括号里的部分

另外，示例代码中应该包含标准输出内容，这样便于读者了解执行情况。标准输出内容在函数内的最后，采用 // Output: 单独起一行开头，剩下的每一行标准输出写一行注释。

相对应地，如果你想要给（不属于任何一个类型的）函数写示例的话，则去掉上文中关于 “类型” 的字段；如果你不需要示例的额外说明符，则去掉 “额外说明” 字段。如下所示:

func ExampleOpt() {
    ........
}

如果一个元素包含多个例子，那么 godoc 会按照字母序对示例及其相应的说明排序。这也就是为什么我干脆在 At() 函数中，示例标为一二三四五的原因，因为这是我希望读者阅读示例的顺序。

在官网上发布 GoDoc

其实发布也很简单：当你将包含了 godoc 的代码 push 之后（比如发布到 github 上），就可以在浏览器中输入 https://pkg.go.dev/${package路径名}。
比如 jsonvalue 的 Github 路径（也等同于 import 路径）为 github.com/Andrew-M-C/go.jsonvalue，因此输入 https://pkg.go.dev/github.com/Andrew-M-C/go.jsonvalue

如果这是该页面第一次进入，那么 pkg.go.dev 会首先获取、解析和更新代码仓库中的文档内容，并且格式化之后展示。
在 pkg.go.dev 中，如果能够找到 package 的最新的 tag 版本，那么会列出 tag（而不是主干分支）上的 GoDoc。

1. 在项目README.md中添加 godoc 徽标

把官网 GoDoc 的链接，附到项目的 README.md 中。
我们可以进入 pkg.go.dev 的 徽章生成页
输入仓库地址（如: https://pkg.go.dev/github.com/iotames/miniutils）, 就可以看到相应的徽标的链接了。
有 html 和 markdown 格式任君选择。

<a href="https://pkg.go.dev/github.com/iotames/miniutils"><img src="https://pkg.go.dev/badge/github.com/iotames/miniutils.svg" alt="Go Reference"></a>

[![Go Reference](https://pkg.go.dev/badge/github.com/iotames/miniutils.svg)](https://pkg.go.dev/github.com/iotames/miniutils)

GitHub徽标:

• badgen.net
• shields.io

[![Go](https://badgen.net/badge/Go/v1.19)](https://go.dev/learn/)
[![GoDoc](https://badgen.net/badge/Go/referenct)](https://pkg.go.dev/github.com/iotames/miniutils)
[![TypeScript](https://badgen.net/badge/UI/antd)](https://ant.design/)
[![License](https://badgen.net/badge/License/MIT/green)](https://gitee.com/catmes/lemocoder)
[![Support](https://badgen.net/badge/Support/linux,win/purple?list=|)](https://gitee.com/catmes/lemocoder)

![](https://img.shields.io/badge/python-3.9-orange)
![](https://img.shields.io/badge/python-3.9-orange?style=for-the-badge&logo=python&logoColor=orange)

2. 发布项目到Git远程仓库并打tag标签

git tag v1.0.0
git push origin --tags
git add .
git commit -m "in order to build my packagist"
git push

• 查看: git tag
• 打标签(默认为最新commit, 可指定): git tag v1.0.1, git tag v2.0.1 37c8036
• 带说明的标签: git tag -a v1.0.1 -m "标签说明"
• 删除标签: git tag -d v1.0.1
• 删除远程标签: git push origin :refs/tags/v1.0.1
• 推送标签到远程: git push origin v1.0.1 or git push origin --tags

快速创建git badge https://badgen.net/ https://shields.io/
List of Badges, in Markdown https://naereen.github.io/badges/
Create a badge https://pkg.go.dev/badge/
作为 Gopher，你知道 Go 的注释即文档应该怎么写吗？ https://cloud.tencent.com/developer/article/1959696?from=10910