在Godoc中记录`package main`需要哪些步骤？

Question

Godoc是用于记录包的一个很好的工具,但是当它被用来反对它时似乎没那么有用package main.我会看到一个输出只显示我用自己//BUG和子目录写给自己的笔记.

Godoc只显示导出的函数,似乎无法从main显示未导出的/函数.我会发现在main中查看函数列表很有用.由于这不受支持,我倾向于在包描述的顶部推送一系列函数,但这感觉就像一个解决方法.

由于我必须手动更新函数列表,因此我经常在软件包中放入尽可能多的代码,以便将其导出并记录下来.这是一个好主意吗？关于main中的函数列表,我该怎么办？

例:

COMMAND DOCUMENTATION

Package main implements a web server, template renderer and DAL for MySQL.

<filename.go>

    <function>(<signature>)

main.go

    main()
    bootstrap() error
    <more functions here>


BUGS

    [filename.go] <whatever...>


SUBDIRECTORIES

    auth
    common
    debug
    storage
    <more packages here>

Answer 1

您需要构建一个稍微修改过的版本godoc来记录主包.

请参阅https://github.com/golang/go/issues/5727.

TL;博士:

1. 修改以下行 $GOPATH/src/golang.org/x/tools/godoc/server.go

   - info.IsMain = pkgname == "main"
   + info.IsMain = false && pkgname == "main"
   

2. 构建和安装go install golang.org/x/tools/cmd/godoc.

$GOPATH/bin/godoc 现在应该按照你的意愿行事.

Answer 2

AFAIK,你已经有了问题的答案.我可以想到两种替代解决方案:

1. 维护一个显示main包函数的godoc分支.(然后你必须自己在网络服务器上运行它的一个实例.缺点是人们直接去godoc.org获取你的软件包文档会遗漏.)
2. 将您的main包分成子包,使main包很小或很小.然后可以在这些子包中读取文档.但据我所知,这并不是普遍的做法.

我认为一般来说,godoc用于包文档.main包的文档实际上只对编辑该包的源代码的人有用 - 因此可以想象文档不需要公开.另一方面,这缺乏godoc的漂亮表现/组织.

作为妥协,如果您真的想要宣传文档,我建议您对程序的体系结构进行概述,而不是每个函数的逐个播放.