Godoc文档未输出列表 [英] Godoc documentation not outputting lists

问题描述

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

I have, throughout the project I'm responsible for testing and documenting, created documentation for the functions and methods, in the following format:

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

The boss and other programmers approve of this format, but the problem is that godoc doesn't recognize the list:

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

Is there a way to get the list to be recognized?

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

Visual Studio Code was, to a point, recognizing this documentation just fine, albeit a bit buggy.

推荐答案

正如其他人所述，列表"是指注释中的不会转换为HTML列表(例如< ol> ，< ul> ).

As others noted, "lists" in comments will not be turned into HTML lists (such as <ol>, <ul>).

建议阅读: Godoc:记录Go代码.引用:

Godoc在概念上与Python的 Docstring 和Java的 Javadoc ，但其设计更为简单.godoc读取的注释不是语言构造(例如Docstring)，也不能具有自己的机器可读语法(例如Javadoc).Godoc的评论只是很好的评论，即使godoc不存在，您也想阅读它.

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文档时仅执行以下转换:

Only the following transformations are performed when generating HTML docs:

Godoc在将注释转换为HTML时会使用一些格式设置规则:

There are a few formatting rules that Godoc uses when converting comments to 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.

以下是列表:

-第一项

第二项

-第三项

这是结束行.

为了使外观更美观，请使用项目符号•而不是破折号:

A slight variation giving better visual appearance is to use the bullet • character instead of the dash:

// 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 使用它):

Results in (github.com/google/go-cmp uses it):

Fv1只是一个例子.

Fv1 is just an example.

以下是列表:

•第一项

•第二项

•第三项

这是结束行.

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

Or you may indent the list items (1 additional space is enough, but you can use more to your liking):

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

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

Which yields this in the generated doc:

Fv2只是另一个例子.

Fv2 is just another example.

以下是列表:

-First item
-Second item
-Third item

这是结束行.

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

You may create "nested" lists like this, identation is kept (as it will be a pre-formatted 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只是另一个示例.

Fv3 is just another example.

以下是列表:

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

这是结束行.

这篇关于Godoc文档未输出列表的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！