Godoc 格式化

Godoc为格式化文档提供了一些特定的语法。

• 段落之间需要有一个空行：

  // Good:// LoadConfig reads a configuration out of the named file.//// See some/shortlink for config file format details.

• 测试文件可以包含可运行的例子，这些例子出现在 godoc 中相应的文档后面：

  // Good:func ExampleConfig_WriteTo() {  cfg := &Config{    Name: "example",  }  if err := cfg.WriteTo(os.Stdout); err != nil {    log.Exitf("Failed to write config: %s", err)  }  // Output:  // {  //   "name": "example"  // }}

• 缩进的行数再加上两个空格，就可以将它们逐字排开：

  // Good:// Update runs the function in an atomic transaction.//// This is typically used with an anonymous TransactionFunc:////   if err := db.Update(func(state *State) { state.Foo = bar }); err != nil {//     //...//   }

  然而，请注意，把代码放在可运行的例子中，而不是把它放在注释中，往往会更合适。 这种逐字格式化可以用于非godoc原生的格式化，如列表和表格：

  // Good:// LoadConfig reads a configuration out of the named file.//// LoadConfig treats the following keys in special ways://   "import" will make this configuration inherit from the named file.//   "env" if present will be populated with the system environment.

• 一行以大写字母开始，除括号和逗号外不含标点符号，后面是另一个段落，其格式为标题：

  复制代码// Good:// The following line is formatted as a heading.//// Using headings//// Headings come with autogenerated anchor tags for easy linking.