为 API 库生成更好的 GoDoc

Question

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

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

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

有没有什么好的方法可以让 GoDoc 的库 API 更清晰，除了 为函数调用添加注释？

Answer 1

我认为 api 包的一个例子是 github 包装器：https://godoc.org/github.com/google/go-github/github.

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

中的方法中看到多个可能的组

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