在 go 函数注释中编写代码块的正确方法是什么？

【问题标题】：What is the proper way to write a code block in a go function comment?在 go 函数注释中编写代码块的正确方法是什么？
【发布时间】：2021-01-26 13:48:13
【问题描述】：

我想在我的函数注释中包含一些示例代码，如下所示：

// Some example for using `foo`:
//
// ```
//   f := Foo(...)
//   g := Goo(f)
// ```
func Foo() {
  ...
}

但是代码块在vscode中显示不正确。正确的做法是什么？

【问题讨论】：

【解决方案1】：

删除那些反引号并缩进代码：

// Foo does ... (note this first line)
// Some example for using Foo:
//
//   f := Foo(...)
//   g := Goo(f)
func Foo() {
  ...
}

Godoc 在将 cmets 转换为 HTML 时使用了一些格式规则：

随后的文本行被视为同一段落的一部分；您必须在段落之间留一个空行。

预格式化文本必须相对于周围的评论文本缩进（参见 gob 的 doc.go 示例）。

URL 将被转换为 HTML 链接；不需要特殊标记。