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代码能够很好地识别这个文档，尽管有些错误。

Answer 1

更新： Go 1.19 beta1已经发布，这增加了对godoc改进的支持：

Doc评论 Go 1.19在文档注释中添加了对链接、列表和更清晰标题的支持。作为这一更改的一部分，gofmt现在重新格式化文档注释，以使其呈现的含义更加清晰。请参阅“去医生的评论”，以了解gofmt当前突出显示的常见错误的语法细节和描述。

从Go 1.19开始，您现在可以添加多种类型的列表，只需缩进行并使用标记，如*、+、-或•，后面跟着空格或制表符。如果使用数字后跟点作为标记，也可以使用编号列表。

例如：

// This will be rendered as a list:
//   - list item #1
//   - list item #2
//   - list item #3

最初的答案如下。

正如其他人所指出的，注释中的“列表”不会转化为HTML (如<ol>、<ul>)。

推荐阅读：Godoc:记录Go代码。引用其中的话：

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

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

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

• 随后的文本行被认为是同一段落的一部分；您必须在单独的段落中留出空白行。
• 预先格式化的文本必须相对于周围的注释文本缩进(例如，请参阅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只是一个例子。 以下是一份清单： -First项目 -Second项目 -Third项目 这是闭幕式。

给出更好的视觉外观的一个细微的变化是使用子弹·字符而不是破折号：

// 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只是一个例子。 以下是一份清单： ·第一项 第二项 第三项 这是闭幕式。

或者您可以缩进列表项(一个额外的空间就足够了，但您可以根据自己的喜好使用更多)：

// Fv2 is just another example.
//
// Here's a list:
//  -First item
//  -Second item
//  -Third item
//
// This is the closing line.

它在生成的文档中产生这个结果：

Fv2只是另一个例子。 以下是一份清单： -First项目-Second项目-Third项目 这是闭幕式。

您可以创建像这样的“嵌套”列表(因为它将是一个预先格式化的块)：

// 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项目-First.First项目-First.Second项目-Second项目 这是闭幕式。

Answer 2

在未来的"https://github.com/golang/go/issues/51082“(2022年2月)中，这种情况可能会改变。

2022年3月：建议已获接纳，它的一部分在Go 1.19 beta1 (2022年6月)。

这个建议改进了对Go文档注释中的标题、列表和链接的支持，同时保持了与现有注释的向后兼容。 它包括一个新的包go/doc/comment，它为doc注释公开了一个解析的语法树，它还包括对go/printer和因此gofmt的更改，以以标准的方式格式化文档注释。 例如，现有列表将从左边的显示重新格式化为右侧的显示：

2022年6月：CL 415174补充道：

建议的(#51082)新的go doc注释添加支持列表、链接和文档链接，但不支持列表中的链接和文档链接，因此实现这一点。 这实现了#53610

示例：

//  - Do this, or...
//  - See [RFC], or...
//
//    [RFC]: https://datatracker.ietf.org/doc/html/rfc2616
//  - Something else