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

Question

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>

Answer 1

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

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

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

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