go - Godoc 文档不输出列表

Question

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

// 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 可以很好地识别此文档，尽管有点错误。

Answer 1

正如其他人所指出的，评论中的“列表”不会转换为 HTML 列表（例如<ol>, <ul>）。

推荐阅读：Godoc：记录 Go 代码。引用它：

Godoc 在概念上与 Python 的Docstring和 Java 的Javadoc相关，但它的设计更简单。godoc 读取的注释不是语言结构（与 Docstring 一样），它们也不一定有自己的机器可读语法（与 Javadoc 一样）。Godoc 评论只是很好的评论，即使 godoc 不存在，您也想阅读这种评论。

生成 HTML 文档时仅执行以下转换：

Godoc 在将注释转换为 HTML 时使用了一些格式规则：

• 随后的文本行被视为同一段落的一部分；您必须留一个空行来分隔段落。
• 预先格式化的文本必须相对于周围的注释文本缩进（参见 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使用它）：

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

这是结束线。

Answer 2

This might change in the future with "https://github.com/golang/go/issues/51082" (Feb. 2022)

This proposal improves support for headings, lists, and links in Go doc comments, while remaining backwards compatible with existing comments.

It includes a new package, go/doc/comment, exposing a parsed syntax tree for doc comments, and it includes changes to go/printer and therefore gofmt to format doc comments in a standard way.

For example, existing lists reformat from the display on the left to the one on the right: