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

【问题标题】：What steps are needed to document `package main` in Godoc?在 Godoc 中记录 `package main` 需要哪些步骤？
【发布时间】：2014-03-13 18:24:03
【问题描述】：

Godoc 是记录包的好工具，但是当它用于 package main 时，它似乎没那么有用了。我将看到一个仅显示我使用 //BUG 和子目录写给自己的笔记的输出。

Godoc 只显示导出的函数，似乎无法从 main 中显示未导出的 / 函数。我会发现在 main.js 中查看函数列表很有用。由于不支持此功能，因此我倾向于将功能列表放在包说明的顶部，但这感觉像是一种解决方法。

由于我必须手动更新函数列表，因此我经常将尽可能多的代码放入包中，以便将其导出并记录在案。这是一个好主意吗？ 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>

【问题讨论】：

标签： go documentation godoc

【解决方案1】：

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

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

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

作为一种折衷方案，如果您真的想公开文档，我建议您概述一下您的程序架构，而不是逐个播放每个功能。

【讨论】：

【解决方案2】：

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

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

tl;博士：

修改$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 现在应该如你所愿。

【讨论】：