godoc 技巧与注意事项

意义

文档对于代码的意义不用多说。

在golang bolg中已经给出了详细的描述 http://blog.golang.org/godoc-documenting-go-code

我在实战中踩到了不少坑，这里给出更详细的解释以及注意事项。

我们针对golang源码中的注释进行分析得到如下结果

针对Package的文档

Synopsis

参考 http://golang.org/pkg/ 中的Synopsis.

这句话主要出现在针对Package注释中的开头位置。

OverView

参考 http://golang.org/pkg/archive/tar/

是针对Package中的注释出现的。如果出现连接，无需标注，生成文档的时候自动会处理成连接

参考例子与注意事项

包： [$GOROOT/src/encoding/json]

文件：encode.go

// Copyright 2010 The Go Authors.  All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package json implements encoding and decoding of JSON objects as defined in
// RFC 4627. The mapping between JSON objects and Go values is described
// in the documentation for the Marshal and Unmarshal functions.
//
// See "JSON and Go" for an introduction to this package:
// http://golang.org/doc/articles/json_and_go.html
package json

从注释中可以看出第四行是断开的，从第四行开始到package json都为针对包的注释。

目录中Synopsis出现内容为：Package json implements encoding and decoding of JSON objects as defined in RFC 4627.

参考注意事项：

在代码的package上面
在上面不能有空行
注释不能断开(中间不能有空行)
最前面一句话会模块的summary会出现在package index中
第一句话以及之后的内容会出现在OverView中

对比文件：decode.go

// Copyright 2010 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Represents JSON data structure using native Go types: booleans, floats,
// strings, arrays, and maps.

package json

在package上面有空行，因此只是针对文件的注释不显示在godoc中

针对Function

例子：

// Marshaler is the interface implemented by objects that
// can marshal themselves into valid JSON.
type Marshaler interface {
 MarshalJSON() ([]byte, error)
}

我们可以看到：

在函数上面进行注释
中间不能有空行
开始需要 [空格]FunctionName[空格] Summary
然后继续说明

想圈起来说明参数：加缩进
进阶技巧：
例子同理于：Function Package

// Marshaler is the interface implemented by objects that
/*
can marshal themselves into valid JSON.
*/ 
type Marshaler interface {
 MarshalJSON() ([]byte, error)
}

这样不算断开，写文档的时候就方便多了。

针对BUG

// BUG(src): Mapping between XML elements and data structures is inherently flawed:
// an XML element is an order-dependent collection of anonymous
// values, while a data structure is an order-independent collection
// of named values.
// See package json for a textual representation more suitable
// to data structures.

godoc会先查找:[空格]BUG

然后显示在Package说明文档最下面，例子： http://golang.org/pkg/encoding/xml/

针对Example

文件名惯用：example_test.go（其他也可以）
包名： apckage_test
方法名：
1. OverView中： Example
2. 方法中： Example[FuncName]
3. 方法中+一些模式：Example[FuncName]_[Mod]

例子查看：

http://golang.org/pkg/errors/

Example文件(example_test.go)：

// Copyright 2012 The Go Authors.  All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package errors_test

import (
 "fmt"
 "time"
)

// MyError is an error implementation that includes a time and message.
type MyError struct {
 When time.Time
 What string
}

func (e MyError) Error() string {
 return fmt.Sprintf("%v: %v", e.When, e.What)
}

func oops() error {
 return MyError{
  time.Date(1989, 3, 15, 22, 30, 0, 0, time.UTC),
  "the file system has gone away",
 }
}

func Example() {
 if err := oops(); err != nil {
  fmt.Println(err)
 }
 // Output: 1989-03-15 22:30:00 +0000 UTC: the file system has gone away
}

注意文件名为：example_test.go
注意package名为 errors_test
针对Function的注释会出现在网页的Example中
如果函数名直接叫Example会直接显示在OverView中

参考文件(errors_test.go)：

// Copyright 2011 The Go Authors.  All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package errors_test

import (
 "errors"
 "fmt"
 "testing"
)

func TestNewEqual(t *testing.T) {
 // Different allocations should not be equal.
 if errors.New("abc") == errors.New("abc") {
  t.Errorf(`New("abc") == New("abc")`)
 }
 if errors.New("abc") == errors.New("xyz") {
  t.Errorf(`New("abc") == New("xyz")`)
 }

 // Same allocation should be equal to itself (not crash).
 err := errors.New("jkl")
 if err != err {
  t.Errorf(`err != err`)
 }
}

func TestErrorMethod(t *testing.T) {
 err := errors.New("abc")
 if err.Error() != "abc" {
  t.Errorf(`New("abc").Error() = %q, want %q`, err.Error(), "abc")
 }
}

func ExampleNew() {
 err := errors.New("emit macho dwarf: elf header corrupted")
 if err != nil {
  fmt.Print(err)
 }
 // Output: emit macho dwarf: elf header corrupted
}

// The fmt package's Errorf function lets us use the package's formatting
// features to create descriptive error messages.
func ExampleNew_errorf() {
 const name, id = "bimmler", 17
 err := fmt.Errorf("user %q (id %d) not found", name, id)
 if err != nil {
  fmt.Print(err)
 }
 // Output: user "bimmler" (id 17) not found
}