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</pre> 
從注釋中可以看出第四行是斷開的，從第四行開始到package json都為針對包的注釋。 

目錄中Synopsis出現內容為：Package json implements encoding and decoding of JSON objects as defined in RFC 4627. 

參考注意事項： 


在代碼的package上面 

在上面不能有空行 

注釋不能斷開(中間不能有空行) 

最前面一句話會模塊的summary會出現在package index中 

第一句話以及之后的內容會出現在OverView中 
</ol>

對比文件：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</pre> 
在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 

然后繼續說明 

想圈起來說明參數： 加縮進 
</ol>

進階技巧： 

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

方法名： 

OverView中： Example 

方法中： Example[FuncName] 

方法中+一些模式：Example[FuncName]_[Mod] 
</ul>
</li>
</ol>

例子查看：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
}</pre> 

注意文件名為：example_test.go 

注意package名為 errors_test 

針對Function的注釋會出現在網頁的Example中 

如果函數名直接叫Example會直接顯示在OverView中 
</ol>

參考文件(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
}</pre> 

ExampleNew就是針對New的例子 

ExampleNew_errorf 給例子加名字詳細效果可以查看這里 
</ol>

針對godoc命令 

我常用兩種方式： 


godoc -http=:6060 直接運行網頁上的版本，很方便 

godoc package [name ...] 在開發的時候文檔速查 
</ol>

總結 

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

我沒搞定的：怎么能顯示成Main函數的，并且能跑Goplayground 
來源： http://www.philo.top/2015/07/10/golang-doc/