生成一个更好的API库的GoDoc

huangapple go评论92阅读模式
英文:

Generating a better GoDoc for API library

问题

我在Go语言中实现了一个典型的REST API库。但是由于端点的数量以及几乎没有共享的不同数据结构,项目的GoDoc非常混乱:

生成一个更好的API库的GoDoc

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

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

除了在函数调用中添加注释之外,是否有一种更好的方法来使库的API在GoDoc中更清晰呢?

英文:

I implemented a typical REST API library in Go. But due to the amount of endpoints and different data structures of which almost none are shared between endpoints the GoDoc for the project is very confusing:

生成一个更好的API库的GoDoc

The way it is structured right now makes it hard to see what is returned by the actual functions and requires a lot of scrolling through the document to find the associated structures with the data.

The Endpoints are all part of the API struct as they can share the authentication state between calls to the API, which causes them all to be listed below the GW2Api struct instead of their associated data structures.

Is there a good way to make the library API clearer with GoDoc, aside from
adding comments to function calls?

答案1

得分: 1

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

如果你有一个庞大的API,一个庞大的godoc在某种程度上是不可避免的。请注意,核心对象并没有直接定义数百个方法,而是定义了多个“service”对象,这样可以将方法分组到逻辑组中。我可以看到你的API中可能有多个可能的组。

我认为没有一种非常好的方法可以将方法与它们所操作或返回的结构类型分组,除非对你的API进行重大更改。相反,我们期望用户查找他们想要执行的操作,然后从那里链接到特定的结构类型以供参考。

英文:

One example of an api package that I think does pretty well is the github wrapper: https://godoc.org/github.com/google/go-github/github.

If you have a large api, a bit of a large godoc is somewhat unavoidable. Note that rather than have a million methods defined directly off of client, the core object has multiple "service" objects defined, which allow them to partition the methods into logical groups. I could see multiple possible groups from the methods in your api.

I don't think there is a super good way to group methods with the struct types they act on or return without significant changes to your api. Rather expect people to look for the operations they want to perform, and from there link to the specific struct types for reference.

huangapple
  • 本文由 发表于 2015年11月9日 23:09:22
  • 转载请务必保留本文链接:https://go.coder-hub.com/33612114.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定