为API库生成更好的GoDoc

Question

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:

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?

Answer 1

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.