Go语言之Doc 文档

简介:

对于协作开发或者代码共享来说,文档是一个可以帮助开发者快速了解以及使用这些代码的一个教程,文档越全面、越详细,入门越快,效率也会更高。


在Go语言中,Go为我们提供了快速生成文档以及查看文档的工具,让我们可以很容易地编写查看文档。


Go提供了两种查看文档的方式:一种是使用go doc命令在终端查看。这种适用于使用VIM等工具在终端开发的人员,他们不用离开终端,既可以查看想查看的文档,又可以编码。


第二种方式,是使用浏览器查看的方式。通过godoc命令可以在本机启动一个Web服务,我们可以通过打开浏览器,访问这个服务来查看我们的Go文档。


从终端查看文档


这种方式适用于在终端开发的人员,他们一般不想离开终端,查完即可继续编码,这时候使用go doc命令是很不错的选择。


  hello go help doc
usage: go doc [-u] [-c] [package|[package.]symbol[.method]]

Doc prints the documentation comments associated with the item identified by its
arguments (a package, const, func, type, var, or method) followed by a one-line
summary of each of the first-level items "under" that item (package-level
declarations for a package, methods for a type, etc.).

Flags:
    -c
        Respect case when matching symbols.
    -cmd
        Treat a command (package main) like a regular package.
        Otherwise package main's exported symbols are hidden
        when showing the package's top-level documentation.
    -u
        Show documentation for unexported as well as exported
        symbols and methods.


从以上可以看出,go doc的使用比较简单,接收的参数是包名,或者是包里的结构体、方法等。如果我们不输入任何参数,那么显示的是当前目录的文档,下面看个例子。


/*
 提供的常用库,有一些常用的方法,方便使用
 */
package lib

// 一个加法实现
// 返回a+b的值
func Add(a,b int) int {
    return a+b
}
  lib go doc
package lib // import "flysnow.org/hello/lib"

提供的常用库,有一些常用的方法,方便使用

func Add(a, b int) int


在当前目录执行go doc,输出了当前目录下的文档信息。


除此之外,我们还可以指定一个包,这样就能列出当前这个包的信息,它包括文档、方法、结构体等。


  lib go doc json
package json // import "encoding/json"

Package json implements encoding and decoding of JSON as defined in RFC
4627. The mapping between JSON and Go values is described in the
documentation for the Marshal and Unmarshal functions.

See "JSON and Go" for an introduction to this package:
https://golang.org/doc/articles/json_and_go.html

func Compact(dst *bytes.Buffer, src []byte) error
func HTMLEscape(dst *bytes.Buffer, src []byte)
func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
func Marshal(v interface{}) ([]byte, error)
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
func Unmarshal(data []byte, v interface{}) error
type Decoder struct{ ... }
    func NewDecoder(r io.Reader) *Decoder
type Delim rune
type Encoder struct{ ... }
    func NewEncoder(w io.Writer) *Encoder
type InvalidUTF8Error struct{ ... }
type InvalidUnmarshalError struct{ ... }
type Marshaler interface{ ... }
type MarshalerError struct{ ... }
type Number string
type RawMessage []byte
type SyntaxError struct{ ... }
type Token interface{}
type UnmarshalFieldError struct{ ... }
type UnmarshalTypeError struct{ ... }
type Unmarshaler interface{ ... }
type UnsupportedTypeError struct{ ... }
type UnsupportedValueError struct{ ... }


以上是我们以json包为例,查看该包的文档。从中我们可以看到它有一个名为Decoder的结构体,我们进一步查看这个结构体的文档


  lib go doc json.Decoder
package json // import "encoding/json"

type Decoder struct {
    // Has unexported fields.
}
    A Decoder reads and decodes JSON values from an input stream.


func NewDecoder(r io.Reader) *Decoder
func (dec *Decoder) Buffered() io.Reader
func (dec *Decoder) Decode(v interface{}) error
func (dec *Decoder) More() bool
func (dec *Decoder) Token() (Token, error)
func (dec *Decoder) UseNumber()


现在我们看到这个Decoder有很多方法,进一步查看这些方法的文档,比如Decode


  lib go doc json.Decoder.Decode    
func (dec *Decoder) Decode(v interface{}) error
    Decode reads the next JSON-encoded value from its input and stores it in the
    value pointed to by v.

    See the documentation for Unmarshal for details about the conversion of JSON
    into a Go value.


go doc的使用就是这样,一步步,缩小范围,查看想看的那些包、结构体、接口或者函数方法的文档。


在线浏览文档


go doc终端查看的方式,虽然也很便捷,不过效率不高,并且没有查看细节以及进行跳转,为此Go为我们提供了基于浏览器使用的网页方式进行浏览API文档。我们只需要点点鼠标,就可以查看了。还可以在方法、包等之间进行跳转,更简洁方便。


要想启动一个Web在线API文档服务很简单,使用godoc就可以了


  lib godoc -http=:6060


后面的http是要指定Web服务监听的IP和Port,运行后,我们就可以打开浏览器,输入http://127.0.0.1:6060进行访问了。你会发现,打开的页面和GoLang的官方网站一样。没错,这其实就是官网的一个拷贝,但是包的文档http://127.0.0.1:6060/pkg/会和官网不一样,你自己启动的这个服务,是基于你电脑上GOROOTGOPATH这两个路径下的所有包生成的文档,会比官网里的只是标准库的文档要多。


在线浏览API文档非常方便,只需要鼠标点击就可以了;也可以点击蓝色的超链接在方法、结构、接口以及包等之间跳转;还可以查看对应的源代码、示例代码,很方便,我们经常用的也是这个在线浏览方式。


生成自己的文档


Go文档工具,还有一个亮点,就是可以支持开发人员自己写代码,只要开发者按照一定的规则,就可以自动生成文档了。


在我们编码中,文档就是注释,Go语言采用了和C、Java差不多的注释风格。一种是双斜线的方式,一种是斜线和星号的方式。


/*
 提供的常用库,有一些常用的方法,方便使用
 */
package lib

// 一个加法实现
// 返回a+b的值
func Add(a,b int) int {
    return a+b
}


这还是我们刚刚的那个例子,例子中文档的编写有两种风格。想要为哪些标识符生成文档,就在哪些标识符之前,使用注释的方式,加入到代码中即可。


现在我们不管是用go doc,还是godoc都可以看到我们刚刚注释的文档了。


添加文档示例


我们在看很多官方API文档的时候,可以在文档里看到一些例子,这些例子会告诉我们怎么使用API,以及这个例子打印的输出是什么。我觉得这个非常好,这样看函数文档看不懂的人,就可以参考这个例子。那么对于我们自己写的API,怎么给API文档添加示例代码呢?


这里我参考了官方的源代码,总结了测试了一下,发现可行,这里分享一下。


  1. 示例代码必须单独存放在一个文件中,文件名字为example_test.go

  2. 在这个go文件里,定义一个名字为Example的函数,参数为空。

  3. 示例的输出采用注视的方式,以//Output:开头,另起一行,每行输出占一行。


说了这三个规则,下面通过一个例子更直观的了解。


package lib

import "fmt"

func Example() {
    sum:=Add(1,2)
    fmt.Println("1+2=",sum)
    //Output:
    //1+2=3
}


这就是为刚刚那个Add函数写的示例代码,我们运行godoc就可以看到结果了。



本文转自 baby神 51CTO博客,原文链接:http://blog.51cto.com/babyshen/1929530,如需转载请自行联系原作者

相关文章
|
3天前
|
安全 Go 调度
Go语言中的并发编程
Go语言自带了强大的并发编程能力,它的协程机制可以让程序轻松地实现高并发。本文将从并发编程的基础概念出发,介绍Go语言中的协程机制、通道和锁等相关知识点,帮助读者更好地理解并发编程在Go语言中的实践应用。
|
1天前
|
数据采集 Web App开发 Go
Go语言与chromedp结合:实现Instagram视频抓取的完整流程
使用Go语言和chromedp库,本文展示了如何抓取Instagram的视频文件,同时通过代理IP保障爬虫稳定和隐私。步骤包括安装chromedp、配置代理(如亿牛云),创建Chrome会话,导航至Instagram,提取视频URL,然后下载视频。关键操作有设置代理服务器、启动Chrome会话、抓取和下载视频。提供的代码示例详细解释了实现过程,有助于开发者学习Instagram数据采集。
Go语言与chromedp结合:实现Instagram视频抓取的完整流程
|
1天前
|
缓存 Go 调度
浅谈在go语言中的锁
【5月更文挑战第11天】本文评估了Go标准库`sync`中的`Mutex`和`RWMutex`性能。`Mutex`包含状态`state`和信号量`sema`,不应复制已使用的实例。`Mutex`适用于保护数据,而`RWMutex`在高并发读取场景下更优。测试显示,小并发时`Mutex`性能较好,但随着并发增加,其性能下降;`RWMutex`的读性能稳定,写性能在高并发时低于`Mutex`。
131 0
浅谈在go语言中的锁
|
2天前
|
存储 安全 编译器
go语言中进行不安全的类型操作
【5月更文挑战第10天】Go语言中的`unsafe`包提供了一种不安全但强大的方式来处理类型转换和底层内存操作。包含两个文档用途的类型和八个函数,本文也比较了不同变量和结构体的大小与对齐系数,强调了字段顺序对内存分配的影响。
59 8
go语言中进行不安全的类型操作
|
2天前
|
Go
配置go语言下载包 - 蓝易云
这个命令会将包下载到你的GOPATH目录下,并自动安装它。
56 1
|
5天前
|
Ubuntu Unix Linux
【GO基础】1. Go语言环境搭建
【GO基础】1. Go语言环境搭建
|
6天前
|
JSON 前端开发 Go
lucky - go 语言实现的快速开发平台
go 语言实现的快速开发平台,自动生成crud代码,前端页面通过json配置,无需编写前端代码。
11 0
|
7天前
|
存储 Java Go
Go 语言切片如何扩容?(全面解析原理和过程)
Go 语言切片如何扩容?(全面解析原理和过程)
16 2
|
7天前
|
负载均衡 Go 调度
使用Go语言构建高性能的Web服务器:协程与Channel的深度解析
在追求高性能Web服务的今天,Go语言以其强大的并发性能和简洁的语法赢得了开发者的青睐。本文将深入探讨Go语言在构建高性能Web服务器方面的应用,特别是协程(goroutine)和通道(channel)这两个核心概念。我们将通过示例代码,展示如何利用协程处理并发请求,并通过通道实现协程间的通信和同步,从而构建出高效、稳定的Web服务器。
|
7天前
|
算法 Go 分布式数据库
构建高可用的分布式数据库集群:使用Go语言与Raft共识算法
随着数据量的爆炸式增长,单一数据库服务器已难以满足高可用性和可扩展性的需求。在本文中,我们将探讨如何使用Go语言结合Raft共识算法来构建一个高可用的分布式数据库集群。我们不仅会介绍Raft算法的基本原理,还会详细阐述如何利用Go语言的并发特性和网络编程能力来实现这一目标。此外,我们还将分析构建过程中可能遇到的挑战和解决方案,为读者提供一个完整的实践指南。