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不识别列表:
有没有办法让列表被识别?
在某种程度上,Visual Studio Code 可以很好地识别此文档,尽管有点错误。
解决方案
正如其他人所指出的,评论中的“列表”不会转换为 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
这是结束线。
推荐阅读
- laravel - 为什么我无法运行 npm 脚本?
- python - 返回 OpenCV 图像作为响应并在浏览器中显示
- python-3.x - 有没有办法以编程方式每行有 4 张卡?
- python - 仅为自动执行禁用 Python 单元测试?
- python - 为什么“python3 [command]”不做任何事情?
- javascript - 脚本不会自行停止
- javascript - 用一个值应该被冻结的变量定义一个函数
- laravel - Stripe PHP 使用 Stripe-cli 调试 SignatureVerificationException 的最佳方法
- sql - SQL 根据 id 获取值
- sqlite - SQlite FTS 表未填充