Document response formats for commands at /api/v0/

[teknomunk]

As seen on this page, the response sections of every API call have no explanation of the returned fields. In one instance in particular, /api/v0/add, there is enough confusion about the Name and Hash fields to spawn a forum thread trying to determine what the Name field actually returns.

Proposed change:

• Add text following each response JSON that detail what the responses are, expected values and similar information that would be useful to a developer using the API.

[johnnymatthews]

We've recently added some automation tools to create the HTTP API docs every time there's a new Go-IPFS release. It might be possible to add in details of the responses of the API into this automation tooling.

[johnnymatthews]

So here's the deal: adding the details of each return value into the current automation processes we have is possible, but requires a very large PR and a bunch of effort. First, the returns fields have to be documented in the code. Then, the HTTP-DOCS-API (that now lives in ipfs-docs/tools) has to be updated to use Go reflect to parse out the comments and put them into the doc. I'm not saying that we shouldn't do this, we absolutely should; I'm just reflecting in the level of work that needs to go into the mentioned tools in order to close this issue. We likely need more discussion around this.

[lidel]

I agree, what is missing is providing the ./tools/http-docs-api generator with information about returned structures.

My 2 cents are that to ensure we have meaningful docs, this should be:

• fully automated (no plaintext edited by humans – it always gets out fo date)
• mandatory (required by the go-ipfs-cmds library)

Perhaps we could extend cmds.Command (go-ipfs-cmds) with a mandatory field that specifies format of response and then use golang's reflection to read that structure in http-docs-api generator and document --enc=json responses used on HTTP API?

I've added it to the maintenance board of Go stewards, could be a good tribute task (doable <1week).