5

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

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

4

2 回答 2

12

正如其他人所指出的,评论中的“列表”不会转换为 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

这是结束线。

于 2018-10-10T16:41:17.710 回答
3

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:

https://raw.githubusercontent.com/golang/proposal/master/design/51082/list-before.png https://raw.githubusercontent.com/golang/proposal/master/design/51082/list-after.png

于 2022-02-10T08:47:22.450 回答