Request: Keep a single copy of the API documentation

[mtlynch]

Feature Request

API documentation is split and duplicated between doc/API.md and doc/api/*. Can we just have a single copy? I mean either merge detailed information into API.md or just throw out the summary versions in API.md and use the more detailed versions in doc/api/*.

Maintaining good documentation is difficult to begin with. Having two copies makes it harder than it needs to be.

I don't really understand the use case for the short-form documentation. Are there developers that want to call an API but don't want to see all the information required for using the API properly?

I'm willing to do this work myself, but I just want to make sure it's what you want.

[DavidVorick]

We split it into separate pages because I think one comprehensive document would be completely overwhelming.

We kept the summary page because I felt it would be helpful to have a single place to view all api calls at once.

My favorite methods for dealing with the API involve javascript, where you can have a collapsed document that lists all of the modules. Clicking a module expands all the routes for that module. Clicking a route expands to provide full documentation, comments, and examples for that one route.

Overall it is my goal that our API is easy to understand and work with. I'm not quite sure what you are suggesting, but I agree our API documentation could move further in the direction of the overall goal.

---

Would you prefer to just throw out the summary entirely and leave the rest? Move everything to a single document with a summary at the top? Move the summary to inside the doc/api/ folder, but rename it to summary.md?

Open to suggestions, but would like to review the overall plan before you put any work into cleanup.

[lukechampine]

perhaps we should consider using a standardized API documentation format (e.g. Swagger, apiDoc, etc.). These allow you to automatically generate nice-looking interactive documentation for a set of routes. I like being able to read them in plaintext too though, so ideally the tool would support that as well.

[DavidVorick]

I'm definitely okay with using a standardized tool of some sort. Some of them really clutter your code though, would want to pick one that's not too invasive. Though, if it really makes it easier to explore + use the API, it's probably a worthwhile tradeoff even if it does make the api code uglier.

[lukechampine]

I don't like cluttering the code either; I was hoping we could find a tool that doesn't require you to annotate your source code. There's a greater risk of the docs being outdated, I guess, but I prefer that to ugly comment directives.

[DavidVorick]

We also have a strict compatibility promise on our api. The worst that we should run into is that a new feature isn't documented.

[mtlynch]

Overall it is my goal that our API is easy to understand and work with. I'm not quite sure what you are suggesting, but I agree our API documentation could move further in the direction of the overall goal.

Would you prefer to just throw out the summary entirely and leave the rest? Move everything to a single document with a summary at the top? Move the summary to inside the doc/api/ folder, but rename it to summary.md?

My main issue is just that there's currently a lot of duplication. It's harder to maintain and it's less discoverable. Someone looking for documentation on /renter/upload/*siapath may find it on API.md and then not realize there's more detailed documentation available in doc/api/Renter.md (this happened to me last week).

The options I see are:

1. Merge everything into a single page (Stick with simple Github Markdown)
   • I don't think this is actually as overwhelming as you think. I personally like long single pages where I can just Ctrl+F to find what I need and I think lots of developers are similar. Even with everything merged together, wouldn't we still be about the typical length of a Go std lib doc page?
2. Get rid of the API.md summary page and move everything to per-module doc pages. (Stick with simple Github Markdown)
3. Switch to a standard documentation tool

I don't have strong opinions about which to do. I volunteer to do the work if you pick (1) or (2).

[DavidVorick]

How would you feel if we simplified API.md? We make API.md so that it's got an overview of the API, the return codes, the error handling, etc. And then it's got a simple enumeration of all the routes, with no description or return values for them. Then you've got a clean page where you can see all the routes for all the modules, and an obvious place to read about all the general info (authentication and errors and stuff), but it's also obvious that you need to read the other pages if you want to actually learn about the routes.

We could move this new API.md into the api folder, and perhaps call it README.md even, so that github automatically renders it as the description when you are in the folder.

[mtlynch]

How would you feel if we simplified API.md? We make API.md so that it's got an overview of the API, the return codes, the error handling, etc. And then it's got a simple enumeration of all the routes, with no description or return values for them. Then you've got a clean page where you can see all the routes for all the modules, and an obvious place to read about all the general info (authentication and errors and stuff), but it's also obvious that you need to read the other pages if you want to actually learn about the routes.

That sounds good.