Godoc文档未输出列表

时间:2018-10-10 16:05:04

标签: go godoc

在我负责测试和记录的整个项目中,我以下列格式创建了有关功能和方法的文档:

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

1 个答案:

答案 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
     

这是结束行。