golang go doc 与 godoc 文档生成查看
Go语言项目十分重视代码的文档,在软件设计中,文档对于软件的可维护和易使用具有重大的影响。因此,文档必须是书写良好并准确的,与此同时它还需要易于书写和维护。
Go语言注释
Go语言中注释一般分为两种,分别是单行注释和多行注释
- 单行注释是以
//
开头的注释,可以出现在任何地方。 - 多行注释也叫块注释,以
/*
开头,以*/
结尾,不可以嵌套使用,一般用于包的文档描述或注释成块的代码片段。
每一个 package
都应该有相关注释,在 package
语句之前的注释内容将被默认认为是这个包的文档, package
的注释应该提供一些相关信息并对整体功能做简要的介绍。
在日常开发过程中,可以使用go doc
和godoc
命令生成代码的文档。
go doc
go doc
命令打印Go语言程序实体上的文档。可以使用参数来指定程序实体的标识符。
Go语言程序实体是指变量、常量、函数、结构体以及接口。
程序实体标识符就是程序实体的名称。
go doc 用法
go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]
可用的标识:
标识 | 说明 |
---|---|
-all | 显示所有文档 |
-c | 匹配程序实体时,大小写敏感 |
-cmd | 将命令(main包)视为常规程序包,如果要显示main包的doc,请指定这个标识 |
-src | 显示完整源代码 |
-u | 显示未导出的程序实体 |
示例
输出指定 package ,指定类型,指定方法的注释
$ go doc sync.WaitGroup.Add
输出指定 package ,指定类型的所有程序实体,包括未导出的
$ go doc -u -all sync.WaitGroup
输出指定 package 的所有程序实体(非所有详细注释)
$ go doc -u sync
godoc
godoc
命令主要用于在无法联网的环境下,以web形式,查看Go语言标准库和项目依赖库的文档。
在 go 1.12
之后的版本中,godoc
不再做为go编译器的一部分存在。依然可以通过go get
命令安装:
go get -u -v golang.org/x/tools/cmd/godoc
国内的安装方法
mkdir -p $GOPATH/src/golang.org/x
cd $GOPATH/src/golang.org/x
git clone https://github.com/golang/tools.git
cd tools/cmd/godoc
go install
ls -alh $GOPATH/bin
通过终端查看文档
go doc命令
$ go doc help usage: go doc [-u] [-c] [package|[package.]symbol[.method]]
可以看到,go doc接受的参数,可以是包名,也可以是包里的结构、方法等,默认为显示当前目录下的文档。
查看系统log包信息
linux@ubuntu:/usr/local/go/src/log$ go doc package log // import "log"Package log implements a simple logging package. It defines a type, Logger, with methods for formatting output. It also has a predefined 'standard' Logger accessible through helper functions Print[f|ln], Fatal[f|ln], and Panic[f|ln], which are easier to use than creating a Logger manually. That logger writes to standard error and prints the date and time of each logged message. Every log message is output on a separate line: if the message being printed does not end in a newline, the logger will add one. The Fatal functions call os.Exit(1) after writing the log message. The Panic functions call panic after writing the log message.const Ldate = 1 << iota ... func Fatal(v ...interface{}) func Fatalf(format string, v ...interface{}) func Fatalln(v ...interface{}) func Flags() int func Output(calldepth int, s string) error func Panic(v ...interface{}) func Panicf(format string, v ...interface{}) func Panicln(v ...interface{}) func Prefix() string func Print(v ...interface{}) func Printf(format string, v ...interface{}) func Println(v ...interface{}) func SetFlags(flag int) func SetOutput(w io.Writer) func SetPrefix(prefix string) type Logger struct{ ... }func New(out io.Writer, prefix string, flag int) *Logger
列出当前包中方法、结构、常量等
查看系统log包中Fatal方法
linux@ubuntu:/usr/local/go/src/log$ go doc log.Fatal func Fatal(v ...interface{})Fatal is equivalent to Print() followed by a call to os.Exit(1).
列出当前函数和注释说明
查看系统log包中Logger结构
linux@ubuntu:/usr/local/go/src/log$ go doc Logger type Logger struct {// Has unexported fields. }A Logger represents an active logging object that generates lines of outputto an io.Writer. Each logging operation makes a single call to the Writer'sWrite method. A Logger can be used simultaneously from multiple goroutines;it guarantees to serialize access to the Writer.func New(out io.Writer, prefix string, flag int) *Logger func (l *Logger) Fatal(v ...interface{}) func (l *Logger) Fatalf(format string, v ...interface{}) func (l *Logger) Fatalln(v ...interface{}) func (l *Logger) Flags() int func (l *Logger) Output(calldepth int, s string) error func (l *Logger) Panic(v ...interface{}) func (l *Logger) Panicf(format string, v ...interface{}) func (l *Logger) Panicln(v ...interface{}) func (l *Logger) Prefix() string func (l *Logger) Print(v ...interface{}) func (l *Logger) Printf(format string, v ...interface{}) func (l *Logger) Println(v ...interface{}) func (l *Logger) SetFlags(flag int) func (l *Logger) SetOutput(w io.Writer) func (l *Logger) SetPrefix(prefix string)
列出Logger结构定义以及Logger结构操作的方法集
通过网页查看文档
godoc命令
$ godoc -http=:6060
godoc会监听6060端口,通过网页访问
http://127.0.0.1:6060
,godoc基于GOROOT和GOPATH路径下的代码生成文档的。打开首页如下,我们自己项目工程文档和通过go get的代码文档都在Packages中的Third party里面。
编写自己的文档
1、设计接口函数代码
创建documents/calc.go文件
/* 简易计算器计算自定义包*/ package documents// 一种实现两个整数相加的函数, // 返回值为两整数相加之和 func Add(a, b int) int {return a + b }// 一种实现两个整数相减的函数, // 返回值为两整数相减之差 func Sub(a, b int) int {return a - b }// 一种实现两个整数相乘的函数, // 返回值为两整数相乘之积 func Mul(a, b int) int {return a * b }// 一种实现两个整数相除的函数, // 返回值为两整数相除之商 func Div(a, b int) int {if b == 0 {panic("divide by zero")}return a / b }
2、设计Example示例代码
创建documents/calc_test.go文件,给calc.go中每个函数编写Example函数
package documentsimport ("fmt" )func ExampleAdd() {result := Add(4, 2)fmt.Println("4 + 2 =", result)// Output:// 4 + 2 = 6 }func ExampleSub() {result := Sub(4, 2)fmt.Println("4 - 2 =", result)// Output:// 4 - 2 = 2 }func ExampleMul() {result := Mul(4, 2)fmt.Println("4 * 2 =", result)// Output:// 4 * 2 = 8 }func ExampleDiv() {result := Div(4,2)fmt.Println("4 / 2 =", result)// Output:// 4 / 2 = 2 }
3、网页查看文档
注意以上两个文件必须在$GOPATH/src路径下,使用godoc命令创建文档,用网页打开显示如下
编写文档规则
1、文档中显示的详细主体内容,大多是由用户注释部分提供,注释的方式有两种,单行注释"//"和代码块"/* */"注释。
2、在源码文件中,在package
语句前做注释,在文档中看到的就是Overview部分, 注意:此注释必须紧挨package
语句前一行,要作为Overview部分的,注释块中间不能有空行。
3、在函数、结构、变量等前做注释的,在文档中看到的就是该项详细描述。注释规则同上。
4、编写的Example
程序,函数名必须以Example
为前缀,可将测试的输出结果放在在函数尾部,以"// Output:"另起一行,然后将输出内容注释,并追加在后面。
golang go doc 与 godoc 文档生成查看相关推荐
- 将doc文档生成html页面
小编在参与某个项目的时候,产品经理要求将产品的操作指南生成html页面的形式直接以链接的形式在管理后台中进行查看,当听到这个要求时小编是相当头疼啊,产品的操作指南将近百来页,不可能手动一页页做成htm ...
- 利用Freemarker模板生成doc或者docx文档(转载整理)
可以直接看主要代码实现 doc作为模板文件生成指定格式的doc文件 实现逻辑 1.把作为模板的doc文件另存为xml文件 2.凡是需要填充的数据用${xxxx}替代 3.利用Template类将数据填 ...
- java利用Freemarker模板生成格式友好的doc或者docx文档
之前写过一篇利用Freemarker模板生成doc的博客,不过那个博客有点缺陷,不支持生成docx格式的文档.所以,这里补充一篇,生成docx或doc格式的文档以具体的docx模板或者doc模板为主. ...
- 再见丑陋的 SwaggerUI,这款API文档生成神器界面更炫酷,逼格更高!
欢迎关注方志朋的博客,回复"666"获面试宝典 一般在使用 Spring Boot 开发前后端分离项目的时候,都会用到 Swagger.Swagger 是一个规范和完整的框架,用于 ...
- 将Doc或者Docx文档处理成html的代码逻辑;统计word中的字数,段数,句数,读取word中文档内容的代码逻辑...
将Doc或者Docx文档处理成html的代码逻辑 下面是maven的配置代码: <!-- 文档处理所需的jar的依赖 --><dependency><groupId> ...
- delphi ui编辑工具源码_一种无侵入比swagger-ui兼容性更好更简单的API文档生成方案
在后端项目中,难免遇到需要写接口文档方便第三方调用的场景,一般业界最常用的方案是使用swagger.Java项目中,一般采用springfox项目,它集成了swagger和swagger-ui,不需要 ...
- 文档生成组件工作估算
笔者最近做一个系统的工作量预估,其中包含一个通用组件,文档生成组件的工作量预估,在此分享下. 功能要求:通过定制文档模板,依据设置的文档数据,抽取数据或图表,生成文档,记录所有生成文档,实现文档查询. ...
- 将Doc或者Docx文档处理成html的代码逻辑;统计word中的字数,段数,句数,读取word中文档内容的代码逻辑
将Doc或者Docx文档处理成html的代码逻辑 下面是maven的配置代码: <!-- 文档处理所需的jar的依赖 --><dependency><groupId> ...
- wsdl文档中的soap:address的生成规则_BAT大牛都在使用的数据库文档生成插件,不来看一下?...
一.概述 在企业级开发中.我们经常会有编写数据库表结构文档的时间付出,从业以来,待过几家企业,关于数据库表结构文档状态:要么没有.要么有.但都是手写.后期运维开发,需要手动进行维护到文档中,很是繁琐. ...
最新文章
- CCNA的一个综合实验(经典)
- 一文读懂机器学习中的正则化
- 从 Java 到 Scala(一):面向对象谈起
- QML资源加载和网络透明度
- linux cpio(copy in/out) 命令详解
- TF从文件中读取数据
- PAT 00-自测1. 打印沙漏(20)
- python实战1.1——根据1.0做词云图
- FKGE:合格的知识图谱嵌入已经学会保护隐私啦!
- 计算机组成实验八,计算机组成原理实验八内存系统实验
- UBNT ex-r +netgear gs105e v2 +ap 设置vlan 步骤记录 及相关知识整理
- bzoj 5094: 硬盘检测(概率)
- 都是过客,相煎何急?
- html内容change事件,HTML onvolumechange事件用法及代码示例
- Windows安装curl及基本命令
- ORACLE数据库查询锁表语句sql脚本,以及删除锁信息脚本(数据库开发ETL、DBA必备)
- 第5节 服务器系统简介及用户和组管理
- csgo开箱网站有哪些?NEW
- UE5 植被系统详解
- 如何用Python求解微分方程组