Godoc 文档不输出列表

2024-04-17

在整个项目中,我负责测试和记录,为函数和方法创建了文档,格式如下:

// CheckPermissionArray checks that values is an array that contains the `expectedValue`
//
// Parameters:
//
// - `values` : the array to check
// - `expectedValue` : the value to search for
//
// Returns:
//
// - an error iff `expectedValue` is not in `values`

老板和其他程序员都认可这种格式,但问题是 godoc 不识别该列表:

有没有办法让列表被识别?

在某种程度上,Visual Studio Code 很好地识别了该文档,尽管有点错误。


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

这是结束线。

本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)

Godoc 文档不输出列表 的相关文章

随机推荐