godoc
一. 约定
注释符//后面要加空格, 例如: // xxx
在package, const, type, func等关键字上面并且紧邻关键字的注释才会被展示
// 此行注释被省略
// 此行注释被展示
//
// 此行注释被展示2
package banana
type, const, func以名称为注释的开头, package以Package name为注释的开头
// Package banana …
package banana
// Xyz …
const Xyz = 1
// Abc …
type Abc struct {}
// Bcd …
func Bcd() {}
有效的关键字注释不应该超过3行
// Package banana …
// …
// …
// 最好不要超过三行
package banana
Package的注释如果超过3行, 应该放在当前包目录下一个单独的文件中, 如:doc.go
如果当前包目录下包含多个Package注释的go文件(包括doc.go), 那么按照文件名的字母数序优先显示
//—– doc.go —–
/*
…第一个显示
*/
package banana
//—– e.go —–
// Package banana …第二个显示
package banana
//—– f.go —–
// Package banana …第三个显示
package banana
Package的注释会出现在godoc的包列表中, 但只能展示大约523字节的长度
在无效注释中以BUG(who)开头的注释, 将被识别为已知bug, 显示在bugs区域, 示例
// BUG(who): 我是bug说明
// Package banana …
package banana
如果bug注释和关键字注释中间无换行, 那么混合的注释将被显示在bugs和godoc列表两个区域内
// BUG(who): 我是bug注释
// Package banana …也是pkg注释
package banana
段落:
/*
abc … bcd
Basic(字体加粗变蓝需首字母大写, 中文加粗变蓝需要加上一个大写字母)
abc
…
… 属于Basic的段落
…
bcd
*/
package banana
预格式化:
/*
abc … bcd
Abc(不会加粗变蓝, 预格式化和段落不能同时存在)
abc ... 预格式化需要缩进 ... bcd */ URL将被转化为HTML链接
二. Example
文件必须放在当前包下
文件名以example开头, _连接, test结尾, 如:example_xxx_test.go
包名是当前包名 + _test, 如: strings_test
函数名称的格式func Example[FuncName]_tag
函数注释会展示在页面上
函数结尾加上// Output:注释, 说明函数返回的值
// 文件必须放在 banana包目录下, 名字必须为example_xxx_test.go
// Package banana_test 为banana包的示例
package banana_test
// 此注释将会被展示在页面上
// 此函数将被展示在OverView区域
func Example() {
fmt.Println(“Hello OverView”)
// Output:
// Hello OverView }
// 此函数将被展示在OverView区域, 并展示noOutput标签
func Example_noOutput() {
fmt.Println(“Hello OverView”)
// (Output: )非必须, 存在时将会展示输出结果
}
// 此函数将被展示在Function区域
// Peel必须是banana包实现的方法
func ExamplePeel() {
fmt.Println(“Hello Banana”)
// Output:
// Hello Banana }
// 此函数将被展示在Function区域
// Peel必须是banana包实现的方法, 并展示big标签
func ExamplePeel_big() {
fmt.Println(“Hello Banana”)
// Output:
// Hello Banana } 三. Command line 开启一个godoc小型server, -play可以使用playground运行Example代码 godoc -http=:6060 -play <!-- more --> 针对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
文件名惯用：example_test.go（其他也可以）
包名： apckage_test
方法名：
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
}
注意文件名为：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
}
ExampleNew就是针对New的例子
ExampleNew_errorf 给例子加名字详细效果可以查看这里
针对godoc命令
我常用两种方式： 1. godoc -http=:6060 直接运行网页上的版本，很方便 2. godoc package [name …] 在开发的时候文档速查
