Godoc: documenting Go code  编写良好的文档关于godoc

31 March 2011

The Go project takes documentation seriously. Documentation is a huge part of making software accessible and maintainable. Of course it must be well-written and accurate, but it also must be easy to write and to maintain. Ideally, it should be coupled to the code itself so the documentation evolves along with the code. The easier it is for programmers to produce good documentation, the better for everyone.

To that end, we have developed the godoc documentation tool. This article describes godoc's approach to documentation, and explains how you can use our conventions and tools to write good documentation for your own projects.

Godoc parses Go source code - including comments - and produces documentation as HTML or plain text. The end result is documentation tightly coupled with the code it documents. For example, through godoc's web interface you can navigate from a function's documentation to its implementation with one click.

Godoc is conceptually related to Python's Docstring and Java's Javadoc, but its design is simpler. The comments read by godoc are not language constructs (as with Docstring) nor must they have their own machine-readable syntax (as with Javadoc). Godoc comments are just good comments, the sort you would want to read even if godoc didn't exist.

The convention is simple: to document a type, variable, constant, function, or even a package, write a regular comment directly preceding its declaration, with no intervening blank line. Godoc will then present that comment as text alongside the item it documents. For example, this is the documentation for the fmt package's Fprintfunction:

// 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) {

Notice this comment is a complete sentence that begins with the name of the element it describes. This important convention allows us to generate documentation in a variety of formats, from plain text to HTML to UNIX man pages, and makes it read better when tools truncate it for brevity, such as when they extract the first line or sentence.

Comments on package declarations should provide general package documentation. These comments can be short, like the sort package's brief description:

// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort

They can also be detailed like the gob package's overview. That package uses another convention for packages that need large amounts of introductory documentation: the package comment is placed in its own file, doc.go, which contains only those comments and a package clause.

When writing package comments of any size, keep in mind that their first sentence will appear in godoc's package list.

Comments that are not adjacent to a top-level declaration are omitted from godoc's output, with one notable exception. Top-level comments that begin with the word "BUG(who)” are recognized as known bugs, and included in the "Bugs” section of the package documentation. The "who” part should be the user name of someone who could provide more information. For example, this is a known issue from the bytes package:

// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.

Sometimes a struct field, function, type, or even a whole package becomes redundant or unnecessary, but must be kept for compatibility with existing programs. To signal that an identifier should not be used, add a paragraph to its doc comment that begins with "Deprecated:" followed by some information about the deprecation. There are a few examples in the standard library.

There are a few formatting rules that Godoc uses when converting comments to HTML:

  • Subsequent lines of text are considered part of the same paragraph; you must leave a blank line to separate paragraphs.
  • Pre-formatted text must be indented relative to the surrounding comment text (see gob's doc.go for an example).
  • URLs will be converted to HTML links; no special markup is necessary.

Note that none of these rules requires you to do anything out of the ordinary.

In fact, the best thing about godoc's minimal approach is how easy it is to use. As a result, a lot of Go code, including all of the standard library, already follows the conventions.

Your own code can present good documentation just by having comments as described above. Any Go packages installed inside $GOROOT/src/pkg and any GOPATH work spaces will already be accessible via godoc's command-line and HTTP interfaces, and you can specify additional paths for indexing via the -path flag or just by running "godoc ." in the source directory. See the godoc documentation for more details.

By Andrew Gerrand

Related articles

31 Godoc: documenting Go code 编写良好的文档关于godoc的更多相关文章

  1. 编写 R Markdown 文档

    数据分析师的工作不仅是将数据放入模型并得出一些结论.通常需要完成从数据收集.数据清理.可视化.建模再到最后编写报告或制作演示文稿的完整工作流程.在前面几章中,我们从不同方面深入学习 R 编程语言,从各 ...

  2. [日常] 编写HTTP接口文档

    一.什么是接口文档?在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护.二.为什么要写接口 ...

  3. 使用swagger来编写在线api文档

    swagger是一个非常简单,强大的框架.快速上手,只需要引入jar包 , 使用注解就可以生成一个漂亮的在线api文档 pom.xml <dependency> <groupId&g ...

  4. 使用 VS Code + Markdown 编写 PDF 文档

    背景介绍 作为一个技术人员,基本都需要编写技术相关文档,而且大部分技术人员都应该掌握 markdown 这个技能,使用 markdown 来编写并生成 PDF 文档将会是一个不错的体验,以下就介绍下如 ...

  5. 从零开始编写自己的C#框架(4)——文档编写说明

    在写本系列的过程中,了解得越多越不知道从哪里做为切入点来写,几乎每个知识点展开来说都可以写成一本书.而自己在写作与文档编写方面来说,还是一个初鸟级别,所以只能从大方面说说,在本框架开发所需的范围内来讲 ...

  6. 使用 VS Code 撰写 Markdown 文档

    众所周知, VS Code 是微软和社区一起开发的一款很优秀的高级代码编辑器.它不仅可以写出一手好代码,还能写出一篇好文章.利用 Markdown 就可以写出一篇排版美观的技术文章了. 而 Markd ...

  7. Rust初步(二):使用Visual Studio Code编写Rust程序(猜猜看游戏)

    我是照着下面这篇帮助文档,完成了第一个完整的Rust程序: 猜猜看 游戏 http://kaisery.gitbooks.io/rust-book-chinese/content/content/3. ...

  8. [6278009]使用Visual Stuido Code 编写Markdown

    使用Visual Stuido Code 编写Markdown void main() { printf("Hello world!"); } void main() { Cons ...

  9. 在ubuntu下使用visual studio code编写python

    感觉有了visual studio code之后,不管编写什么语言的代码都可以,简单安装对应的语言插件即可. 这不轮到了最近比较热的python语言,蹭着AI的热度,python语言成为了工程师们又一 ...

随机推荐

  1. Java之IO流(字节流,字符流)

    IO流和Properties IO流 IO流是指计算机与外部世界或者一个程序与计算机的其余部分的之间的接口.它对于任何计算机系统都非常关键, 因而所有 I/O 的主体实际上是内置在操作系统中的.单独的 ...

  2. JVM 垃圾回收机制和常见算法

    垃圾回收机制:释放那些不再持有引用的对象的内存. 如何判断对象是否需要回收? 引用计数:对象,内存,磁盘空间等被引用次数保存起来,次数为0时将其进行释放. 对象引用遍历:对象应用遍历从一组对象开始,沿 ...

  3. Java类编译、加载、和执行机制

    Java类编译.加载.和执行机制 标签: java 类加载 类编译 类执行 机制 0.前言 个人认为,对于JVM的理解,主要是两大方面内容: Java类的编译.加载和执行. JVM的内存管理和垃圾回收 ...

  4. ASP.NET MVC 3 常用

    http://blog.csdn.net/churujianghu/article/details/7297358 1.ASP.NET MVC 3 如何去除默认验证 这个默认验证是在web.confi ...

  5. Python如何引入自定义模块?

    Python运行环境在查找库文件时是对 sys.path 列表进行遍历,如果我们想在运行环境中注册新的类库,主要有以下四种方法: 1.在sys.path列表中添加新的路径.这里可以在运行环境中直接修改 ...

  6. 六、java异常处理

    目录 一.异常的概念 二.异常的分类 三.异常的捕获和处理 四.使用自定义异常 一.异常的概念 java异常是指java提供的用于处理程序运行过程中错误的一种机制 所谓错误是指在程序运行的过程中发生的 ...

  7. Nginx Upstream Keepalive 分析 保持长连接

    Nginx Upstream长连接由upstream模式下的keepalive指令控制,并指定可用于长连接的连接数,配置样例如下: upstream http_backend {     server ...

  8. Windows 下安装和配置 MongoDB(二)

    因为电脑重新安装了系统,所以要重新安装开发环境,按照之前写过的一篇博客介绍的步骤进行安装,发现报了一些错误,下面是遇到的问题和解决方法: 首先下载安装就不多说了,下载地址:https://www.mo ...

  9. NOIP2011 提高组 Day1

    自测:8:27——11:51 实际得分:100+60+20=180 期望得分:100+60+40=200 T3读错题,失20 http://cogs.pro/cogs/page/page.php?ai ...

  10. 使用object_box遇到的崩溃 java.lang.UnsatisfiedLinkError:

    java.lang.UnsatisfiedLinkError: dalvik.system.PathClassLoader[DexPathList[[zip file "/data/app/ ...