文档章节

Godoc中的Example编写

secondriver
 secondriver
发布于 2015/09/30 15:25
字数 612
阅读 359
收藏 0

Godoc

godoc工具可以从go程序中抽取出并生成文档,抽取的内容来自go代码中的注释,以及本文中将要讲到的源代码包下的example_test.go文件。

起因

Go语言还算是比较新的东西,学习资料并不是太多。在查看go的document的时候,看到Example的时候有些纳闷,代码文档注释中并没有标识那些东西作为Example,于是查看了源代码包,发现了example_test.go这个文件,原来猫腻在这里,通常在一个包下添加该文件后,就可以在里面添加Example

经过

查看example_test.go的文件内容之后得出了以下结论:

  • 如果为函数添加Example, 直接在example_test.go文件中添加函数func Example{要提供示例的函数名}
func ExampleDesEncrypt() {
	var data = "Hello World !"
	var goodkey = "abcd1234"
	security, err := DesEncrypt([]byte(data), []byte(goodkey))
	if err != nil {
		t.Error(err)
	}
	d, err := DesDecrypt(security, []byte(goodkey))
	if err != nil {
		log.Fatal(err)
	}
	if string(d) != data {
		log.Fatal(data, goodkey, string(security), string(d))
	} else {
		log.Println("Ok")
	}
}

  • 如果为方法添加Example, 直接在example_test.go文件中添加函数func Example{方法接受者结构体类型名}_{要提供示例的方法名}
func ExampleCutImage_CutSrcImage() {
	var src = "src.png"
	var w, h = 100, 100
	for i := 20; i < 800; i += 100 {
		var cutIamge = CutImage{
			SrcImageFileName:   src,
			DestImageFileName:  "dest" + strconv.Itoa(i) + ".png",
			DestImageWidth:     w,
			DestImageHeight:    h,
			SrcImageStartPoint: image.Point{X: i, Y: i},
		}
		//裁剪图片
		err := cutIamge.CutSrcImage()
		if err != nil {
			log.Fatal(err)
		}
	}
}

  • 如果为类型添加Example,直接在example_test.go文件中添加函数fun Example{类型名}
func ExampleCutImage() {
	var cutIamge = CutImage{
		SrcImageFileName:   "src.png",
		DestImageFileName:  "dest.png",
		DestImageWidth:     100,
		DestImageHeight:    100,
		SrcImageStartPoint: image.Point{X: 0, Y: 0},
	}

	_ := cutIamge.CutSrcImage()
}
  • 如果添加Example的函数名,类型名,方法名不存在,将会在godoc抽取生成文档是忽略,如下:
2015/09/30 14:45:28 skipping example 'ExampleCutSrcImage' because 'CutSrcImage' is not a known function or type
2015/09/30 14:52:53 skipping example 'ExampleCutImage_CutSrcImage2' because 'CutImage_CutSrcImage2' is not a known function or type

结果

通过为ximage包,xdes包中的函数添加Example可以使得初次使用的时候更容易获得正确的使用方法。

下面秀出在go document中Example的具体效果:

Go Document Example

图a: Go Document中的Example展示部分

ximage包中的类型方法Example

图b: ximage包中的类型方法Example

xdes包中的函数Example

图c: xdes包中的函数Example

© 著作权归作者所有

secondriver
粉丝 10
博文 229
码字总数 233821
作品 0
广州
程序员
私信 提问
Simple http download and readline lib by Golang--Go Curl

Curl: 用GO编写的HTTP下载和解析库 Documentation Visit the docs on GoDoc Importing go get github.com/Kenshin/curl Usage import "github.com/Kenshin/curl" Example See https://github......

王磊-Kenshin
2014/06/04
1K
0
如何维护一个自己的 golang doc 服务

本文内容是如何维护一个golang 在线的doc 服务。 1 什么是godoc ? godoc 是 golang 官方提供的文档生成工具, 2 为什么要有godoc ? 我们经常遇到一个问题,就是代码和文档不一致,线上代码版...

鼎铭
01/16
349
0
译文:写在Go测试代码中例子(原文:Testable Examples in Go)

原文: 简介 Go自动生成的文档中有时你会看到代码例子,这些例子还可以通过点击网站上的Run按钮运行。而这些例子是从测试代码中提取出来的。 这些代码例子是具有可测性的,而带来的优点就是当...

go-skyblue
2016/05/05
164
0
Robotgo v0.70.0 发布了, 增强 keyboard 和 mouse 操作

Robotgo v0.70.0 发布了,Golang 跨平台控制鼠标、键盘、位图、屏幕、窗口句柄以及全局事件监听。 [查看更新详情和项目地址] # Caloris Montes ### Add - [NEW] Update keyboard use sendIn...

vz
01/08
569
0
Robotgo v0.60.0 发布, 重构 window 和 example

Robotgo v0.60.0 Mount Olympus: Mytikas 发布了,Golang 跨平台控制鼠标、键盘、位图、屏幕、窗口句柄以及全局事件监听。 查看详细更新地址 Add [NEW] Add GetBounds func support (add ge...

vz
2018/10/10
306
0

没有更多内容

加载失败,请刷新页面

加载更多

rime设置为默认简体

转载 https://github.com/ModerRAS/ModerRAS.github.io/blob/master/_posts/2018-11-07-rime%E8%AE%BE%E7%BD%AE%E4%B8%BA%E9%BB%98%E8%AE%A4%E7%AE%80%E4%BD%93.md 写在开始 我的Arch Linux上......

zhenruyan
今天
4
0
简述TCP的流量控制与拥塞控制

1. TCP流量控制 流量控制就是让发送方的发送速率不要太快,要让接收方来的及接收。 原理是通过确认报文中窗口字段来控制发送方的发送速率,发送方的发送窗口大小不能超过接收方给出窗口大小。...

鏡花水月
今天
8
0
OSChina 周日乱弹 —— 别问,问就是没空

Osc乱弹歌单(2019)请戳(这里) 【今日歌曲】 @tom_tdhzz :#今日歌曲推荐# 分享容祖儿/彭羚的单曲《心淡》: 《心淡》- 容祖儿/彭羚 手机党少年们想听歌,请使劲儿戳(这里) @wqp0010 :周...

小小编辑
今天
876
10
golang微服务框架go-micro 入门笔记2.1 micro工具之micro api

micro api micro 功能非常强大,本文将详细阐述micro api 命令行的功能 重要的事情说3次 本文全部代码https://idea.techidea8.com/open/idea.shtml?id=6 本文全部代码https://idea.techidea8....

非正式解决方案
今天
5
0
Spring Context 你真的懂了吗

今天介绍一下大家常见的一个单词 context 应该怎么去理解,正确的理解它有助于我们学习 spring 以及计算机系统中的其他知识。 1. context 是什么 我们经常在编程中见到 context 这个单词,当...

Java知其所以然
昨天
6
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部