go语言学习笔记——godoc的使用（超详细，含示例文件）

godoc使用教程

注释规范

• 注释符//后面要加空格, 例如: // xxx

    在注释符要缩进的话，第二行注释符后面的空格要比上一行的空格多一个
    example:
        // 123
        //  123
  

• 注释要紧跟package、const、type、func这些关键字，这样子才会被显示

    // 功能: 函数H的注释
    //  参  数:
    //     	h1	: 说明参数值
    //     	h2	: 运算的数字
    //  返回值:
    //     	reValue 	: 返回值
    
    //你会发现函数H的功能注释没有显示，这是因为功能函数注释与关键字func之间空了一行
    func H(h1 string, h2 string) (reValue string) {
        fmt.Println(h1, h2)
        return h1
    }
  

• package的注释最好不好超过3行，不过就算超过3行也没有关系。这里只是做一个规范而已。如果对于pkg描述的注释有很多行的时候，我们可以新建一个doc.go，这个文件用于对package包的描述

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

    详细等会看实例文件        
  

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

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

在终端查看

在终端，进入要查看的包的目录go doc显示当前包的文档
这里查看的是包名的文档，以及所有的函数名字跟变量类型名

example:
    go doc
    
terminal show:
    package test // import "test/testdoc"
    这个是a.go的包名的描述


    At 20191017 by Baiyu
    
    ---a.go end---
    
    这个是在doc.go 文件中的内容
    
    在Go的源代码中
    
    在Mac系统中
    
    在类Unix系统中
    
    在Windows系统中
    
    ---doc.go end---
    
    这个是在testgodoc.go文件的内容 package Name: test
    
        describe:    程序的入口
    
    ---testgodoc.go end---
    
    这个是z.go 的包名描述
    
    ---z.go end---
    
    const Email ...
    const Baiyu = "baiyu"
    func H(h1 string, h2 string) (reValue string)
    func Test(param1 string, inter int) (k string)
    func Z()
    type Computer struct{ ... }
    type Person struct{ ... }
    
    BUG: 这个注释会生成在文档最后后面，同时因为紧跟着fun Z，所以在上面的func列表里面也有显示
    功能: 生成Z签名
    
    BUG: 因为前面有BUG(who)这个关键字，所以这句注释就算没有紧跟关键字不会被隐藏掉
    
    BUG: BUG(6):格式正确，所以这句注释就算没有紧跟关键字不会被隐藏掉，前面的BUG():、BUG6:、BUG:都是不正确的BUG(who)命名

go doc <pkg>.<func>查看pkg包下面的func函数的注释

example:
    go doc test.Test
    
terminal show:
     package test // import "test/testdoc"
     func Test(param1 string, inter int) (k string)
        功能: 测试函数
   
        参  数:
            param1  : 说明参数值
            inter   : 运算的数字
        返回值:
            k       : 返回值

如果想查看完整的源码go doc -src <pkg>.<func>

example: 
    go doc -src test.Test 
    
terminal show:
    package test // import "test/testdoc"
    // 功能: 测试函数
    //  参  数:
    //      param1  : 说明参数值
    //      inter   : 运算的数字
    //  返回值:
    //      k       : 返回值
    func Test(param1 string, inter int) (k string) {
            fmt.Println("测试函数")
            return param1
    }

在浏览器上查看

使用命令godoc -http=:6060
然后在打开浏览器的，在url输入localhost:6060/pkg或者127.0.0.1:6060/pkg就可以查看到你本地的所有包的信息了

如果你想要找到你特定的包名的话localhost:6060/pkg/<path>/<packageName>或者127.0.0.1:6060/pkg/<path>/<packageName>

<path>是你/src下包所在的路径

<packageName>是包名

导出godoc文档为HTML

使用命令godoc -url "http://localhost:6060/pkg/<pkg>/<packageName>/" > <packageName>.html

<pkg>是你包所在的文件夹

<packageName>是你的包名

导出来的是纯html文件，没有样式表，不过也有可能可以导出，但是我目前没有找到，如果有找到的朋友也可以交流一下

不过我也有把对应的样式文件给导出来了

下载地址https://github.com/BaiYu96/golandLearn/tree/master/learn_doc/stylefile

然后把html文件里面的css跟js指定的路径修改好就可以

教程示例文件

下载地址https://github.com/BaiYu96/golandLearn/tree/master/learn_doc/test

把test文件夹放到你$GOPATH/src/目录下