第一个是在这里。

由于上次我们调查了如何为自制包添加godoc，所以这次我们将根据此进行调查，看看可以使用什么样的godoc编写方式。

参考： 《Effective Go – 注解》

尝试换个职业

首先，我会尝试一下在适当的位置进行换行，因为如果保持上一次的方式，评论将在一行中显示而没有换行。

$ cd $GOPATH/github.com/chooyan/math
$ vi math.go

尝试将评论从 // 改写为 /* */。

/*
 Package math provides simple functions.
 These are sample functions to practice golang.
*/
package math

func Sum(a int, b int) int {
        return a + b
}

$ godoc github.com/chooyan/math
PACKAGE DOCUMENTATION

package math
    import "github.com/chooyan/math"

    Package math provides simple functions. These are sample functions to
    practice golang.

FUNCTIONS

func Abs(i int) int

func Sum(a int, b int) int

哎呀，换行没有生效。
试着再换一行看看。

/*
 Package math provides simple functions.

 These are sample functions to practice golang.
*/
package math
...略

$ godoc github.com/chooyan/math
PACKAGE DOCUMENTATION

package math
    import "github.com/chooyan/math"

    Package math provides simple functions.

    These are sample functions to practice golang.

FUNCTIONS
...略

哦，换行了。
在尝试了各种方法后，似乎加入空行或稍微缩进一字符就会发生换行的情况。

/*
 Package math provides simple functions.
  These are sample functions to practice golang.
 list
  -a
  -b
  -c
*/
package math
...略

$ godoc github.com/chooyan/math
PACKAGE DOCUMENTATION

package math
    import "github.com/chooyan/math"

    Package math provides simple functions.

        These are sample functions to practice golang.

    list

        -a
        -b
        -c

FUNCTIONS
...略

虽然有点难理解，但一旦习惯了，代码中只需缩进和换行即可轻松地编写出漂亮的godoc，看起来很方便。

尝试为函数添加godoc。

函数的基本内容相同。

...略
// Sum is a function to sum up given a and b
func Sum(a int, b int) int {
        return a + b
}

$ godoc github.com/chooyan/math

...略
FUNCTIONS

func Abs(i int) int

func Sum(a int, b int) int
    Sum is a function to sum up given a and b

当您添加godoc时，函数的定义信息将显示在下方。

在godoc中编写函数的方式建议如下。

如果名称总是在注释开始，那么godoc的输出可以通过grep进行有用的运行。

据说，如果将函数名称放在文章开头，即使记不起函数名称，也可以通过相关的单词来轻松找到函数。

虽然文档中没有写明，但按照这样做的话，当根据函数名进行grep搜索时，只能显示函数定义和godoc，看起来效果不错。

我觉得只要这么简单，我就会认真地去写文档。