GO 文档笔记

前言

最开始写 GO 的时候, 发现方法的注释并不支持@param, @return等参数, 搞得我都不知道该如何给自己的方法写文档说明了. 而且网上搜了搜也没有搜到教程, 甚是郁闷.

今天找到了GO内置的文档工具: godoc. (我用的1.14.3版本貌似不是自带工具了, 需要安装(配置代理): go get golang.org/x/tools/cmd/godoc)

运行命令: godoc -http=:8888. 可以直接在本地浏览器访问8888端口, 查看这个运行在本地的文档服务: localhost:8888. 能够看到所有官方包的文档. 而这些文档内容都是从官方代码包中读取的.

这个文档工具不光能够检测官方文档, 还能够检测自己的项目, 只要将项目配置到GOPATH下即可.

image-20200719145327838

既然人家官方代码能生成文档, 那就说明是有文档生成格式的呀. 既然我不知道如何写文档, 抄官方的样式不就行了么? nice. 以下是我多处借鉴后, 总结的 GO 文档书写规则.

文档

经过测试, GO 的文档格式, 全局变量/常量/函数/结构体/接口/包等等, 声明格式都一样, 会读取对应内容上方紧跟着的注释内容. 所以就对文档格式统一介绍即可.

文档格式

书写格式

文档的书写影响其展示形式, 如下所示:

/*
这是一个展示文档作用的包.

A 标题

这里的标题为首字母大写, 且后面没有标点.
如果没有空行, 则文档不会换行.

B标题二

GO 的文档工具只识别首字母大写, 不识别中文, 有点难受.
 开头空格标识缩进
 */
// 同时, 也可以写成多个单行注释的形式
package doc

展示形式:

对于包的说明文档, 因为包下每个文件都有package doc 这段代码, 如果包下有多个文件都对此包进行了说明, 文档会将所有说明拼接到一起. 可以单独建一个doc.go的空文件, 专门用来写包文档. (fmt 包就是这么搞的)

全局变量/常量/方法/结构体

全局变量/常量/方法/结构体等内容, 文档会对其进行归类, 只要将说明加到其上方即可. 简单写个常量看看, 其他同理:

// test const
const TestConst = "const"

示例代码

与写单元测试类似, 新建一个example_test.go文件. 在其中写 demo 函数, 会检测同名以Example开头的函数:

package doc

import (
   "fmt"
)

func ExampleDemoTest() {
   DemoTest()

   // OutPut:
   // 没有返回值
}

// 多个 demo, 下划线后拼单词或数字
func ExampleDemoTest_2() {
   DemoTest()
}

// 包 demo, 对于没有指定方法的, 会识别为这个包的例子
func Example() {
   fmt.Println("aaaa")

   // OutPut:
   // none
}

// 包 demo2
func Example_2() {
   fmt.Println("bbb")
}

godoc检测示例代码:

文档关键字

那 GO 的注释中有没有文档用到的关键字呢? 有, 简单写几个.

BUG

可以对 bug 进行描述, godoc会自动识别并标识出来:

// BUG(hujing): 对 bug 的描述信息

image-20200719161655341

Deprecated

已弃用的标识, 这个关键字看的太多了, 不过godoc并不会识别这个关键字, 主要是编译器识别.

// Deprecated: 请使用 DocDemoNew 方法

注意

  1. 文档注释与对应内容之间不能有空行.
  2. godoc只会对公共内容生成文档, 私有内容不会展示.

GO的文档还有更多, 这里只是简单的整理一下, 对于之后写项目基本够用了, 再也不会在写 GO 文档的时候懵逼了. GO 既然已经提供了godoc这么好的工具, 那写文档就更是义不容辞的工作了.

がんばる!!!

本文分享自微信公众号 - 烟草的香味(hujing-bc),作者:胡靖哥哥

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2020-07-19

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • css中的单位

    前端开发中, 做适配是少不了的, 即页面在各种尺寸的机型中显示效果一样, 这就用到了css中的各种长度单位, 做一下总结

    烟草的香味
  • Java集合的选择

    我们在使用集合时应该使用哪个集合呢? 具体还是要看需求, 当然, Java中不只是有这几个, 还有一些没有给出, 具体情况具体分析吧, 仅给出一个小思路. 简单...

    烟草的香味
  • Python中的+=

    今天在运行之前写的一个Python脚本时,发生了一个奇怪的现象(我怎么老遇到奇怪的现象~~)。当时的代码大概长这样:

    烟草的香味
  • 在RPA项目中有哪些文档,如何使用这些文档

    RPA项目也同样遵循同样的方式,不同的厂商和公司定义的文档类型也不太相同,多的可能十几种,少的也要几种,具体的遵循方式和使用标准取决于公司内部的使用章程。

    RPA小葵
  • 谷歌软件工程师是怎样写设计文档的?

    谷歌软件工程文化的主要元素之一就是通过设计文档定义软件设计。在开始项目编码工作之前,软件系统或应用程序的作者会创建这些相对非正式的文档。设计文档记录了高级实现策...

    深度学习与Python
  • 程序员既要写好代码,又要写好文档

    程序员既要写好代码,又要写好文档 作为一个长期混迹于CSDN社区的人,我对很多拥有高访问量的博主钦佩不已,特别是在参加了CSDN在举办“2014 CSDN博文大...

    用户1289394
  • 读不懂英文文档,能写出代码不?

    作为一个开发人员,开发一个新项目,维护一个项目,想要快速的开展工作。最重要的是干什么?是阅读项目文档,没文档看代码。可见我们首要做的事情是看文档看懂文档,编程初...

    程序员互动联盟
  • DAS 2020 Keynote Speech | Adobe 文档分析技术介绍

    DAS 2020 (Document Analysis System,文档分析系统研讨会) 于 7月26-29日在武汉召开,本次研讨会中有不少精彩的内容,昨天向...

    CV君
  • 文档!文档!文档!重要的事情说三遍!

    项目一期基本开发完毕,包括后台管理系统以及提供给手机端的接口还有SSO,由于奔着敏捷开发去的,文档没有过多花时间去写, 当然了文档肯定有,开发人员写的自己能看懂...

    风间影月
  • Elasticsearch学习-父子文档

    上一篇文章介绍了Elasticsearch的嵌套文档,这一篇来介绍另外一种关系文档,父子文档。

    dalaoyang

扫码关注云+社区

领取腾讯云代金券