14

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>
4

2 回答 2

8

您需要构建一个稍微修改过的版本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现在应该如你所愿。

于 2015-01-22T09:15:14.597 回答
8

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

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

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

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

于 2014-02-15T04:12:05.160 回答