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; DR：

修改$GOPATH/src/golang.org/x/tools/godoc/server.go

中的以下行

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

使用go install golang.org/x/tools/cmd/godoc构建并安装。

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

Answer 2

AFAIK，你已经有了问题的答案。我可以想到两种替代解决方案：

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

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

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

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

2 个答案: