UPDATE:Go 1.19 beta1 已发布,增加了对多项 godoc 改进的支持:
文件评论
Go 1.19 添加了对文档注释中的链接、列表和更清晰标题的支持。作为此更改的一部分,gofmt
现在重新格式化文档注释,使其呈现的含义更加清晰。看“去文档评论” https://tip.golang.org/doc/comment有关语法详细信息和常见错误的描述,现在突出显示gofmt
.
从 Go 1.19 开始,您现在可以添加多种类型的列表,只需缩进行并使用标记,例如*
, +
, -
or •
后跟一个空格或制表符。如果您使用数字后跟一个点作为标记,则还可以使用编号列表。
例如:
// This will be rendered as a list:
// - list item #1
// - list item #2
// - list item #3
原始答案如下。
正如其他人指出的,注释中的“列表”不会转换为 HTML 列表(例如<ol>
, <ul>
).
推荐阅读:Godoc:记录 Go 代码 https://blog.golang.org/godoc-documenting-go-code。引用其中:
Godoc 在概念上与 Python 相关文档字符串 http://www.python.org/dev/peps/pep-0257/和Java的Javadoc http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html,但其设计更为简单。 godoc 读取的注释不是语言结构(如 Docstring),也不一定有自己的机器可读语法(如 Javadoc)。 Godoc 注释只是好的注释,即使 godoc 不存在,您也会想阅读这种注释。
生成 HTML 文档时仅执行以下转换:
将注释转换为 HTML 时,Godoc 使用一些格式规则:
- 后续文本行被视为同一段落的一部分;您必须留空行来分隔段落。
- 预先格式化的文本必须相对于周围的注释文本缩进(参见 gob 的doc.go https://golang.org/src/pkg/encoding/gob/doc.go举个例子)。
- URL 将被转换为 HTML 链接;不需要特殊标记。
您可以对列表进行“模仿”操作:
使用以下评论:
// Fv1 is just an example.
//
// Here's a list:
//
// -First item
//
// -Second item
//
// -Third item
//
// This is the closing line.
产生以下输出:
Fv1只是一个例子。
这是一个列表:
-第一项
-第二项
-第三项
这是结束线。
提供更好视觉外观的细微变化是使用项目符号字符而不是破折号:
// Fv1 is just an example.
//
// Here's a list:
//
// • First item
//
// • Second item
//
// • Third item
//
// This is the closing line.
结果是 (github.com/google/go-cmp https://godoc.org/github.com/google/go-cmp/cmp使用它):
Fv1只是一个例子。
这是一个列表:
• 第一项
• 第二项
• 第三项
这是结束线。
或者您可以缩进列表项(1 个额外的空格就足够了,但您可以根据自己的喜好使用更多空格):
// Fv2 is just another example.
//
// Here's a list:
// -First item
// -Second item
// -Third item
//
// This is the closing line.
在生成的文档中会产生以下结果:
Fv2只是另一个例子。
这是一个列表:
-First item
-Second item
-Third item
这是结束线。
您可以像这样创建“嵌套”列表,保留缩进(因为它将是一个预先格式化的块):
// Fv3 is just another example.
//
// Here's a list:
// -First item
// -First.First item
// -First.Second item
// -Second item
//
// This is the closing line.
文档中的结果:
Fv3 只是另一个例子。
这是一个列表:
-First item
-First.First item
-First.Second item
-Second item
这是结束线。