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

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

Doc Comments

Go 1.19 adds support for links, lists, and clearer headings in doc comments. As part of this change, gofmt now reformats doc comments to make their rendered meaning clearer. See “Go Doc Comments” for syntax details and descriptions of common mistakes now highlighted by gofmt.

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

例如:

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

原始答案如下。

---

正如其他人指出的那样，评论中的“列表”不会转换为 HTML 列表(例如 <ol> 、 <ul> )。

推荐阅读:Godoc: documenting Go code .引用它:

Godoc is conceptually related to Python's Docstring and Java's Javadoc, but its design is simpler. The comments read by godoc are not language constructs (as with Docstring) nor must they have their own machine-readable syntax (as with Javadoc). Godoc comments are just good comments, the sort you would want to read even if godoc didn't exist.

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

There are a few formatting rules that Godoc uses when converting comments to HTML:

• Subsequent lines of text are considered part of the same paragraph; you must leave a blank line to separate paragraphs.
• Pre-formatted text must be indented relative to the surrounding comment text (see gob's doc.go for an example).
• URLs will be converted to HTML links; no special markup is necessary.

你可以做什么来“模仿”列表:

使用以下注释:

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

结果如下:

Fv1 is just an example.

Here's a list:

-First item

-Second item

-Third item

This is the closing line.

提供更好视觉外观的细微变化是使用项目符号 • 字符而不是破折号:

// 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 is just an example.

Here's a list:

• First item

• Second item

• Third item

This is the closing line.

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

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

在生成的文档中产生这个:

Fv2 is just another example.

Here's a list:

-First item
-Second item
-Third item

This is the closing line.

您可以像这样创建“嵌套”列表，并保留标识(因为它将是一个预先格式化的 block ):

// 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 is just another example.

Here's a list:

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

This is the closing line.