为 API 库生成更好的 GoDoc

Question

我在 Go 中实现了一个典型的 REST API 库。但是由于端点的数量和不同的数据结构几乎没有在端点之间共享，因此该项目的 GoDoc 非常混乱：

它现在的结构方式使得很难看到实际函数返回的内容，并且需要大量滚动文档才能找到与数据相关的结构。

端点都是 API 结构的一部分，因为它们可以在对 API 的调用之间共享身份验证状态，这导致它们都列在 GW2Api 结构下方，而不是它们关联的数据结构之下。

有没有一种好方法可以让 GoDoc 中的库 API 更清晰，除了 将 cmets 添加到函数调用中？

Answer 1

我认为做得很好的一个 api 包示例是 github 包装器：https://godoc.org/github.com/google/go-github/github。

如果你有一个大的 api，有点大的 godoc 是不可避免的。请注意，核心对象不是直接从client 定义一百万个方法，而是定义了多个“服务”对象，这允许它们将方法划分为逻辑组。我可以从您的 api 中的方法中看到多个可能的组。

我认为没有一种非常好的方法可以在不对您的 api 进行重大更改的情况下将方法与它们作用或返回的结构类型进行分组。而是期望人们寻找他们想要执行的操作，并从那里链接到特定的结构类型以供参考。