翻译

在看官方文档的时候，突然心血来潮，想翻译一下一篇博客玩玩。 原文章地址 Godoc: documenting Go code Go 语言官方对于代码的文档非常重视，文档对于软件的可阅读性和可维护性有着至关重要的地位。当然，文档必须要是准确可理解的，也需要易于编写和维护。理性情况下，文档应该与代码紧密联系。这样子才能方便于程序员修改和编写。 所以，我们开发了 godoc 文档工具。本文描述了的 godoc 关于的“文档”的方法论，和解释如何按照使用规范给你自己的项目写出一个好的文档。 godoc 会解析源文件代码和注释，生成基于HTML的页面或者纯文本格式的文档。这样子文档就与代码紧密联系。举个例子，通过在 godoc 的页面点击，你就可以在一个函数的文档说明和源代码中快速跳转。 godoc 在概念上与 Python 的“Docstring”和 Java 的“Javadoc"相似，但是 godoc 设计的更加简单化。godoc 读取的代码注释的不需要特定的结构化（Docstring 使用），也不需要特定的语法（JavaDoc 使用），godoc 从代码读取的注释就是简单的“代码注释”，就算你不使用 godoc 也可以直接阅读的注释。 使用的规范很简单：在类型，变量，常量，函数，包声明的上方写下注释即可， 中间不要有空行。godoc 会把这些注释以文字的形式呈现在被注释的对象旁边。举个例子，下方就是 fmt 包的Fprint函数的注释。 1 2 3 4 // Fprint formats using the default formats for its operands and writes to w. // Spaces are added between operands when neither is a string. // It returns the number of bytes written and any write error encountered. func Fprint(w io.Writer, a ...interface{}) (n int, err error) { 值得注意的是该注释是以被注释的对象命名开头的一个完整的句子。 这个使用规范可以方便我们生成各种各样的格式文档，从简单的纯文本到 UNIX 是 man 的帮助页，还可以使用其他工具更见简单地获取到信息， 比如提取出第一行或者句子。 ...