godoc 技巧与注意事项

xiaoxiao2024-01-29 165

文档对于代码的意义不用多说。在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.htmlpackage 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方法名： 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_testimport ( "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_testimport ( "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命令

我常用两种方式：

godoc -http=:6060 直接运行网页上的版本，很方便 godoc package [name ...] 在开发的时候文档速查

总结

一般工程中搞定这些基本就够了。详细的还是要动手做一做。

我没搞定的：怎么能显示成Main函数的，并且能跑Goplayground

原文发布时间为：2015-07-11

本文来自云栖社区合作伙伴“Linux中国