GoDoc的使用

栏目: Go · 发布时间: 6年前

内容简介:开启一个godoc小型server,

一. 约定

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

  2. package, const, type, func关键字 上面并且紧邻关键字的注释才会被展示

    // 此行注释被省略
    
    // 此行注释被展示 
    // 
    // 此行注释被展示2 
    package banana
  3. type, const, func 以名称为注释的开头, packagePackage name 为注释的开头

    // Package banana ...
    package banana
    
    // Xyz ...
    const Xyz = 1
    
    // Abc ...
    type Abc struct {}
    
    // Bcd ...
    func Bcd() {}
  4. 有效的关键字注释不应该超过 3

    // Package banana ...
    // ...
    // ...
    // 最好不要超过三行
    package banana
  5. Package 的注释如果超过 3 行, 应该放在当前包目录下一个单独的文件中, 如: doc.go

  6. 如果当前包目录下包含多个 Package 注释的 go 文件(包括 doc.go ), 那么按照 文件名的字母数序 优先显示

    //----- doc.go -----
    
    /*
    ...第一个显示
    */
    package banana
    //----- e.go -----
    
    // Package banana ...第二个显示
    package banana
    //----- f.go -----
    
    // Package banana ...第三个显示
    package banana
  7. Package 的注释会出现在godoc的 包列表 中, 但只能展示大约523字节的长度

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

    // BUG(who): 我是bug说明
    
    // Package banana ...
    package banana
  9. 如果 bug注释关键字注释 中间无换行, 那么 混合的注释 将被显示在 bugsgodoc列表 两个区域内

    // BUG(who): 我是bug注释
    // Package banana ...也是pkg注释
    package banana
  10. 段落:

    /*
    abc ... bcd
    
    Basic(字体加粗变蓝需首字母大写, 中文加粗变蓝需要加上一个大写字母)
    
    abc
    ...
    ... 属于Basic的段落
    ...
    bcd
    */
    package banana
  11. 预格式化:

    /*
    abc ... bcd
    
    Abc(不会加粗变蓝, 预格式化和段落不能同时存在)
    
        abc ... 预格式化需要缩进 ... bcd
    */
  12. URL将被转化为HTML链接

二. Example

  • 文件必须放在当前包下
  • 文件名以 example 开头, _ 连接, test 结尾, 如: example_xxx_test.go
  • 包名是 当前包名 + _test , 如: strings_test
  • 函数名称的格式 func Example[FuncName][_tag]()
  • 函数注释会展示在页面上
  • 函数结尾加上 // Output: 注释, 说明函数返回的值
// 文件必须放在 banana包目录下, 名字必须为example_xxx_test.go

// Package banana_test 为banana包的示例
package banana_test

// 此注释将会被展示在页面上
// 此函数将被展示在OverView区域
func Example() {
    fmt.Println("Hello OverView")
    
    // Output:
    // Hello OverView
}

// 此函数将被展示在OverView区域, 并展示noOutput标签
func Example_noOutput() {
    fmt.Println("Hello OverView")
    // (Output: )非必须, 存在时将会展示输出结果
}

// 此函数将被展示在Function区域
// Peel必须是banana包实现的方法
func ExamplePeel() {
    fmt.Println("Hello Banana")
    
    // Output:
    // Hello Banana
}

// 此函数将被展示在Function区域
// Peel必须是banana包实现的方法, 并展示big标签
func ExamplePeel_big() {
    fmt.Println("Hello Banana")
    
    // Output:
    // Hello Banana
}

三. Command line

开启一个godoc小型server, -play 可以使用 playground 运行 Example 代码

godoc -http=:6060 -play

四. 参考


以上就是本文的全部内容,希望本文的内容对大家的学习或者工作能带来一定的帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

.NET本质论 第1卷:公共语言运行库

.NET本质论 第1卷:公共语言运行库

博克斯 (BoxDon) / 张晓坤 / 中国电力出版社 / 2004-1 / 48.00元

本书由10章组成,探讨了CLR即公共语言运行库,涵盖了基本类型、实例、方法调用和消息、AppDomain、安全、以及CLR外部世界。一起来看看 《.NET本质论 第1卷:公共语言运行库》 这本书的介绍吧!

JS 压缩/解压工具
JS 压缩/解压工具

在线压缩/解压 JS 代码

RGB转16进制工具
RGB转16进制工具

RGB HEX 互转工具

Markdown 在线编辑器
Markdown 在线编辑器

Markdown 在线编辑器