知识卡片

普通读书笔记卡 · 3905

声明前注释生成文档

理解等级:中级

Go 的文档注释与声明位置绑定:紧邻顶层声明的注释会成为该声明的说明,并被文档工具抽取。行注释通常用 //,块注释常作包说明。注释应写成读者可独立理解的正文,而不是依赖空格对齐、装饰性横幅或额外标记。写注释时同时考虑源码阅读和生成文档,能减少两套说明分叉。

这张卡片看不懂?

已有反馈 · 0 / 10 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    • 注释 · 查看原书依据

      在顶层声明之前出现,并且中间没有换行的注释,会随着声明一起被抽取,作为该项的解释性文本。这些注释的本质和风格决定了godoc所产生文档的质量。

    参考来源

    - 位置:《Effective Go中文版》第03章《注释》(源文件:`_epub-src/OEBPS/注释.md.html`) - 结论依据:原文直接说明 `godoc` 如何抽取顶层声明前注释,并指出生成文档质量取决于注释本身的文字与格式。 - 原始内容:在顶层声明之前出现,并且中间没有换行的注释,会随着声明一起被抽取,作为该项的解释性文本。这些注释的本质和风格决定了 godoc 所产生文档的质量。