搜索
简帛阁>技术文章>Golang中的godoc使用简介(推荐)

Golang中的godoc使用简介(推荐)

go doc简介

Godoc是go语言的文档化工具,类似于文档化工具godoc,类似于Python的Docstring和Java的Javadoc
Godoc通过解析包含注释的Go代码来生成HTML或文本类型的文档。

Golang中的godoc使用简介

学习go语法的同时为了方便查看对应的文档,不同的Go版本会有一些改动,所以,使用本地Go源码生成的文档显然更精确。

go在1.13之前是自带godoc的,之后的版本需要自行安装。

go get -u golang.org/x/tools/cmd/godoc // 并没有自动安装
go install golang.org/x/tools/cmd/godoc // 手动安装

> godoc -h

usage: godoc -http=localhost:6060
  -goroot string
        Go root directory (default "D:\\Go")
  -http string
        HTTP service address (default "localhost:6060")
  -index
        enable search index
  -index_files string
        glob pattern specifying index files; if not empty, the index is read from these files in sorted order
  -index_interval duration
        interval of indexing; 0 for default (5m), negative to only index once at startup
  -index_throttle float
        index throttle value; 0.0 = no time allocated, 1.0 = full throttle (default 0.75)
  -links
        link identifiers to their declarations (default true)
  -maxresults int
        maximum number of full text search results shown (default 10000)
  -notes string
        regular expression matching note markers to show (default "BUG")
  -play
        enable playground
  -templates string
        load templates/JS/CSS from disk in this directory
  -timestamps
        show timestamps with directory listings
  -url string
        print HTML for named URL
  -v    verbose mode
  -write_index
        write index to a file; the file name must be specified with -index_files
  -zip string
        zip file providing the file system to serve; disabled if empty

进入到Go源码目录,D:\Go\src
godoc -http=:6060
扫描文件需要时间,启动之后有时候还要等一会。
访问浏览器 http://localhost:6060/

访问指定的包
http://localhost:6060/pkg/fmt/
http://localhost:6060/pkg/archive/tar/

可以通过godoc -url "http://localhost:6060/pkg/" > doc.html导出为静态的html单个文件,但是这个体验很差。

如果我们要查看一个第三方包的文档,比如 github.com/julienschmidt/httprouter
首先要进入它的源码目录
godoc -http=localhost:6060
第一部分依然是 Go Standard library,第二部分 Third party 才是 httprouter 的文档

如果我们要查看某个项目的文档也可以使用这种方式,然后我就发现我们自己写的项目大多没有什么注释,于是这就牵涉到注释的规范。

注释使用//加一个空格并且要紧跟着被注释对象的上方。

首先需要给package加上注释,说明此包的作用,例如

// Package bufio implements buffered I/O. It wraps an io.Reader or io.Writer
// object, creating another object (Reader or Writer) that also implements
// the interface but provides buffering and some help for textual I/O.
package bufio

同一目录下的包可以由很多个文件组成,如果每个文件都有对package进行注释的话,godoc会自动将所有注释"按照文件名的字母数序"进行合并

在无效注释中以BUG(who)开头的注释, 将被识别为已知bug, 显示在bugs区域

  // BUG(who): 因为前面有BUG(who)这个关键字,所以这句注释就算没有紧跟关键字不会被隐藏掉

关于DEPRECATED弃用

// Time returns an int64 unix timestamp in milliseconds of the snowflake ID time
// DEPRECATED: the below function will be removed in a future release.
func (f ID) Time() int64 {
	return (int64(f) >> timeShift) + Epoch
}

在注释符要缩进的话,第二行注释符后面的空格要比上一行的空格多一个

  example:
      // 123
      //  123

关于 go doc xxx
主要用来在终端上查看某个包的文档,它也是通过扫描包内的一些注释,然后格式化输出,但很少这么用。

> go doc fmt

package fmt // import "fmt"
Package fmt implements formatted I/O with functions analogous to C's printf
and scanf. The format 'verbs' are derived from C's but are simpler.
Printing
The verbs:
General:

    %v  the value in a default format
        when printing structs, the plus flag (%+v) adds field names
    %#v a Go-syntax representation of the value
    %T  a Go-syntax representation of the type of the value
    %%  a literal percent sign; consumes no value
...
...

go doc约定规则

godoc
Go的注释规则很简单,为类型,变量,常量,函数或包编写注释时,直接在这些声明前编写普通形式的注释,中间不留空行即可。Godoc将这些注释与后面的声明连接到一起,达到文档化的目的。

1.注释符// 后加空格

// 这是一行注释
package main

2.注释紧邻关键字行写,否则不会被识别

// 不会被识别
// 会被识别
package main
// 不会被识别
 
// 会被识别1
// 会被识别2
func main(){
}

3.注释行的数量最好不要超过3行

4.已知bug注释:BUG(who)
godoc的输出将忽略那些与顶层声明不相邻的注释,只有一个例外,那就是以BUG(who)开头的注释。这些注释将被识别为已知的bug,并包含在文档的BUGS区。

// 注释
package main
// BUG(who)  //会被识别,放入文档的Bugs区
const a = 8

使用命令

首先在命令行进入所需要执行的.go文档目录
例:我的test.go放在C:/GoProject/src/test/ 目录下
需要在命令行进入C:/GoProject/src/test/
然后执行命令

godoc -http=:6060     //6060是godoc提供的默认端口

在浏览器输入 localhost:6060,即可进入godoc的网站,查看自己的文档需要在地址栏输入路径 localhost:6060/pkg/test

目录godoc简介Golang中的godoc使用简介godoc约定规则使用命令godoc简介Godoc是go语言的文档化工具,类似于文档化工具godoc,类似于Python的Docstring和Jav
目录1Quiz2Answer3ResolvingConclusion1Quiz有如下一个例子:packagemainimport(encoding/jsonfmttime)typeRecordBrie
之前有篇文章比较浅显的分析了一下golang的服务器如何实现,还有Handler,DefaultServeMux,HandlerFunc的用处。我们现在已经明白了DefaultServeMux就是存放
Go中也提供了反射机制,与Java一样Go的反射也是在运行时获取对象的相关信息,更新对象内部状态;Golang通过反射可以获取对象类型、字段类型与值、调用struct实例方法、更新实例值等;Go关于反
Golang程序中有很多种方法来处理命令行参数。简单的情况下可以不使用任何库,直接处理osArgs;其实Golang的标准库提供了flag包来处理命令行参数;还有第三方提供的处理命令行参数的库,比如
笔者在前文中介绍了Golang标准库中flag包的用法,事实上有一个第三方的命令行参数解析包pflag比flag包使用的更为广泛。pflag包的设计目的就是替代标准库中的flag包,因此它具有更强大的
文章目录反射反射类型Type指针结构体反射值Value结构体空与有效性判断修改值函数调用反射三定律interface底层结构ifaceeface反射是一种让程序可以在运行时(runtime)检查其数据
Golang推荐的命名规范很少见人总结一些命名规范,也可能是笔者孤陋寡闻,作为一个两年的golang开发者,我根据很多知名的项目,如moby,kubernetess等总结了一些常见的命名规范。命名规范
女主宣言今天小编为大家分享一篇关于Golang循环汇编分析的文章,文章中介绍了golang循环的汇编层面的处理,通过分析,我们可以更了解循环的实现。希望能对大家有所帮助。PS:丰富的一线技术、多元化的
Go语言最主要的特性代码如下:自动垃圾回收更丰富的内置类型函数多返回值错误处理匿名函数和闭包类型和接口并发编程反射语言交互性高性能/高效开发安装安装说明地址http://golangorg/doc/i