为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之外定义了一百万个方法，而是有多个＆＃34; service＆＃34;定义的对象，允许它们将方法划分为逻辑组。我可以从api中的方法中看到多个可能的组。

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