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

Answer 1

正如其他人指出的那样，注释中的“列表”将不会变成HTML列表（例如<ol>，<ul>）。

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

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

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

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

• 随后的文本行被视为同一段落的一部分；您必须留空行以分隔段落。
• 预先格式化的文本必须相对于周围的注释文本缩进（有关示例，请参阅gob的doc.go）。
• 网址将转换为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.

结果在doc中：

Fv3只是另一个示例。

以下是清单：

-First item
  -First.First item
  -First.Second item
-Second item

这是结束语。

Answer 2

未来这可能会随着“ https://github.com/golang/go/issues/51082 ”（2022 年 2 月）
2022 年 3 月而改变：该提案被接受，部分内容在Go 1.19 beta1（2022 年 6 月）中。

该提案改进了对 Go 文档注释中的标题、列表和链接的支持，同时保持与现有注释的向后兼容。

它包括一个新的包，go/doc/comment公开了文档注释的解析语法树，并且它包括对文档注释的更改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