知识卡片
声明前注释生成文档
Go 的文档注释与声明位置绑定:紧邻顶层声明的注释会成为该声明的说明,并被文档工具抽取。行注释通常用 //,块注释常作包说明。注释应写成读者可独立理解的正文,而不是依赖空格对齐、装饰性横幅或额外标记。写注释时同时考虑源码阅读和生成文档,能减少两套说明分叉。
这张卡片看不懂?
这张卡片的反馈已满 10 条,暂时无法继续提交。
已有反馈 · 0 / 10 条
还没有人提交反馈。
在整书笔记中的位置
- · 第03章 注释
原书出处 · 1 处
- 注释 · 查看原书依据
在顶层声明之前出现,并且中间没有换行的注释,会随着声明一起被抽取,作为该项的解释性文本。这些注释的本质和风格决定了godoc所产生文档的质量。
参考来源
- 位置:《Effective Go中文版》第03章《注释》(源文件:`_epub-src/OEBPS/注释.md.html`)
- 结论依据:原文直接说明 `godoc` 如何抽取顶层声明前注释,并指出生成文档质量取决于注释本身的文字与格式。
- 原始内容:在顶层声明之前出现,并且中间没有换行的注释,会随着声明一起被抽取,作为该项的解释性文本。这些注释的本质和风格决定了 godoc 所产生文档的质量。