Prodive documentation

[Minoru]

(This is a memo.)

So I looked into edoc, the goal being to see if it can:

• help us keep the docs closer to actual function definitions, and
• give us something more readable than a lo-ong list of available functions.

Edoc excels with the first goal, but totally fails the second.

I couldn't find a way to group functions—they're always in the alphabetical order.

I couldn't find a way to document two clauses differently—for each combination of function and its arity there's only one block of docs. This is really painful because we try to make pagination as unobtrusive as possible, which forces us to make things like octo:list_pull_requests(A, B) behave differently depending on the types of A and B. But if we can't document these behaviours separately, the docs are going to confuse people instead of enlightening them.

We'll have to keep using one big Markdown file for this, but I need to come up with a better, more readable formatting for it.

[Minoru]

Tried it the other way—writing a giant list in Markdown—and it doesn't work either.

The reason is that a lot of stuff is shared between functions. Pagination is implemented the same way everywhere. Options are the same everywhere. So I put these topics into separate files and just refer to them. But if I do that, all that's left is… a list that I could've generated with Edoc.

So I started writing these common docs, only to realize that I probably need to write actual functions first to make sure the docs are comprehensive.

As a result, I pushed some scraps into feature/docs branch so that I don't have to start from scratch later, and I'll concentrate on code for now.