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.

參考注意事項：

1. 在程式碼的package上面
2. 在上面不能有空行
3. 註釋不能斷開(中間不能有空行)
4. 最前面一句話會模組的summary會出現在package index中
5. 第一句話以及之後的內容會出現在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)
}

我們可以看到：

1. 在函式上面進行註釋
2. 中間不能有空行
3. 開始需要 [空格]FunctionName[空格] Summary
4. 然後繼續說明
5. 想圈起來說明引數： 加縮排

進階技巧：

例子同理於：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

1. 檔名慣用：example_test.go（其他也可以）
2. 包名： apckage_test
3. 方法名：
   • OverView中： Example
   • 方法中： Example[FuncName]
   • 方法中+一些模式：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
}

1. 注意檔名為：example_test.go
2. 注意package名為 errors_test
3. 針對Function的註釋會出現在網頁的Example中
4. 如果函式名直接叫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
}

1. ExampleNew就是針對New的例子
2. ExampleNew_errorf 給例子加名字詳細效果可以檢視這裡

針對godoc命令

我常用兩種方式：

1. godoc -http=:6060 直接執行網頁上的版本，很方便
2. godoc package [name ...] 在開發的時候文件速查

總結

一般工程中搞定這些基本就夠了。詳細的還是要動手做一做。

我沒搞定的：怎麼能顯示成Main函式的，並且能跑Goplayground