为API库生成更好的GoDoc

Question

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

​

​

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

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

除了向函数调用添加注释之外，是否有一种好的方法可以使GoDoc的库API更清晰？

Answer 1

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

如果您有一个很大的api，那么有点大的godoc是不可避免的。注意，核心对象没有直接在客户端上定义100万个方法，而是定义了多个“服务”对象，从而允许它们将方法划分为逻辑组。我可以从api中的方法中看到多个可能的组。

我不认为有一种超级好的方法可以使用它们所操作或返回的struct类型对方法进行分组，而不会对您的api进行重大更改。而是期望人们查找他们想要执行的操作，并从那里链接到特定的结构类型以供参考。