为 API 库生成更好的 GoDoc

Question

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

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

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

除了在函数调用中添加注释之外，有没有什么好方法可以使用 GoDoc 使库 API 更清晰？

Answer 1

我认为非常好的 api 包的一个示例是 github 包装器：https : //godoc.org/github.com/google/go-github/github。如果你有一个很大的 api，那么有点大的 godoc 有点不可避免。请注意，核心对象不是直接从client定义一百万个方法，而是定义了多个“服务”对象，这允许它们将方法划分为逻辑组。我可以从您的 api 中的方法中看到多个可能的组。我认为没有一种非常好的方法可以将方法与它们作用或返回的结构类型进行分组，而无需对您的 api 进行重大更改。而是期望人们寻找他们想要执行的操作，并从那里链接到特定的结构类型以供参考。