在我负责测试和记录的整个项目中,我以下列格式创建了有关功能和方法的文档:
// 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可以很好地识别此文档,尽管有点问题。
答案 0 :(得分:5)
正如其他人指出的那样,注释中的“列表”将不会变成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
这是结束行。