Home

这里记录文档相关问题

实例代码

见 syscall, html/template

const (
    _ = iota
    OK // comment ok // 翻译 ok
    NO // comment no // 翻译 no
)

// comment 1
type (
    // comment 2
    CSS  string

    // comment 3
    HTML string
)

线上代码

archive/tar const 2015 VS archive/tar const 2016

文档风格

文档不关心常量 "_", 但必须提取此声明生成的 ".go" 文档才符合语法.

习惯上尾注释的翻译是在行尾加翻译. 生成的文档要保持整体风格.

分组本身也可能有注释, 因此分组的整体风格必须被保持.

要防止翻译者破坏分组结构, 或还原分组风格.

问题扩展

排序

不同分组进行排序, 只能按照第一个 Ident 的字面值为依据. 组内不进行排序.

索引

如果生成 Markdown 文档, 很难为分组中的 Ident 生成 "### Ident".

如果进行 HTML 渲染, 需要对分组中的 Ident 进行锚链 ID 设置.

翻译

如果手工修改 godocu 生成的文档, 要注意编辑器很可能配置了 "goimports", 使得文档的 import 段被改写. 再次使用 merge 指令可保证 import 段和源码一致.