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无法识别该列表：

https://towardsdatascience.com/understanding-feature-engineering-part-4-deep-learning-methods-for-text-data-96c44370bbfa

有没有办法让名单得到认可？

在某种程度上，Visual Studio Code可以很好地识别此文档，尽管有点问题。

Answer 1

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

推荐阅读：Godoc: documenting Go code。引用：

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
这是结束行。

Godoc文档未输出列表

1 个答案: