Go语言之Doc 文档

简介: 对于协作开发或者代码共享来说,文档是一个可以帮助开发者快速了解以及使用这些代码的一个教程,文档越全面、越详细,入门越快,效率也会更高。在Go语言中,Go为我们提供了快速生成文档以及查看文档的工具,让我们可以很容易地编写查看文档。

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


在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就可以看到结果了。

640?wx_fmt=png&tp=webp&wxfrom=5&wx_lazy=


Go的文档工具非常强大,更多功能我们可以使用帮助命令查看。这里再推荐一个比较不错的第三方的API文档网站,它收录了包括官方在内的很多Go库,可以直接跳转,关联源代码,非常方便https://gowalker.org/


目录
相关文章
|
2天前
|
Ubuntu Unix Linux
【GO基础】1. Go语言环境搭建
【GO基础】1. Go语言环境搭建
|
3天前
|
JSON 前端开发 Go
lucky - go 语言实现的快速开发平台
go 语言实现的快速开发平台,自动生成crud代码,前端页面通过json配置,无需编写前端代码。
9 0
|
4天前
|
存储 Java Go
Go 语言切片如何扩容?(全面解析原理和过程)
Go 语言切片如何扩容?(全面解析原理和过程)
13 2
|
4天前
|
负载均衡 Go 调度
使用Go语言构建高性能的Web服务器:协程与Channel的深度解析
在追求高性能Web服务的今天,Go语言以其强大的并发性能和简洁的语法赢得了开发者的青睐。本文将深入探讨Go语言在构建高性能Web服务器方面的应用,特别是协程(goroutine)和通道(channel)这两个核心概念。我们将通过示例代码,展示如何利用协程处理并发请求,并通过通道实现协程间的通信和同步,从而构建出高效、稳定的Web服务器。
|
4天前
|
算法 Go 分布式数据库
构建高可用的分布式数据库集群:使用Go语言与Raft共识算法
随着数据量的爆炸式增长,单一数据库服务器已难以满足高可用性和可扩展性的需求。在本文中,我们将探讨如何使用Go语言结合Raft共识算法来构建一个高可用的分布式数据库集群。我们不仅会介绍Raft算法的基本原理,还会详细阐述如何利用Go语言的并发特性和网络编程能力来实现这一目标。此外,我们还将分析构建过程中可能遇到的挑战和解决方案,为读者提供一个完整的实践指南。
|
4天前
|
消息中间件 Go API
基于Go语言的微服务架构实践
随着云计算和容器化技术的兴起,微服务架构成为了现代软件开发的主流趋势。Go语言,以其高效的性能、简洁的语法和强大的并发处理能力,成为了构建微服务应用的理想选择。本文将探讨基于Go语言的微服务架构实践,包括微服务的设计原则、服务间的通信机制、以及Go语言在微服务架构中的优势和应用案例。
|
4天前
|
安全 测试技术 数据库连接
使用Go语言进行并发编程
【5月更文挑战第15天】Go语言以其简洁语法和强大的并发原语(goroutines、channels)成为并发编程的理想选择。Goroutines是轻量级线程,由Go运行时管理。Channels作为goroutine间的通信机制,确保安全的数据交换。在编写并发程序时,应遵循如通过通信共享内存、使用`sync`包同步、避免全局变量等最佳实践。理解并发与并行的区别,有效管理goroutine生命周期,并编写测试用例以确保代码的正确性,都是成功进行Go语言并发编程的关键。
|
4天前
|
数据采集 监控 Java
Go语言并发编程:Goroutines和Channels的详细指南
Go语言并发编程:Goroutines和Channels的详细指南
11 3
|
4天前
|
数据采集 人工智能 搜索推荐
快速入门:利用Go语言下载Amazon商品信息的步骤详解
本文探讨了使用Go语言和代理IP技术构建高效Amazon商品信息爬虫的方法。Go语言因其简洁语法、快速编译、并发支持和丰富标准库成为理想的爬虫开发语言。文章介绍了电商网站的发展趋势,如个性化推荐、移动端优化和跨境电商。步骤包括设置代理IP、编写爬虫代码和实现多线程采集。提供的Go代码示例展示了如何配置代理、发送请求及使用goroutine进行多线程采集。注意需根据实际情况调整代理服务和商品URL。
快速入门:利用Go语言下载Amazon商品信息的步骤详解
|
4天前
|
存储 编译器 Go
Go语言学习12-数据的使用
【5月更文挑战第5天】本篇 Huazie 向大家介绍 Go 语言数据的使用,包含赋值语句、常量与变量、可比性与有序性
50 6
Go语言学习12-数据的使用