Documentation

[iankronquist]

Documentation is especially poor right now. Comments stand at < 10% of code. There are several approaches.

Evaluate:

• Literate C? Is that a thing? What would it involve? It sounds like a cool idea, but we'll have to take a look. Could we produce a Latex PDF or a webpage in one swell foop?
• Doxygen. I've had mixed success before. I like the idea of inline comments. If I do this I would want to check coverage and put it in CI.
• Restructured Text (rst): eww
• Markdown files. I'd rather have it side by side with the code.

[iankronquist]

• Literate C would require rewriting everything into a very special format which could no longer be eaten by the compiler. I really don't like this idea.
• Doxygen is my top pick so far, but maybe I should use yardoc instead. I'm familiar with yardoc and I can use markdown instead of what Doxygen uses.

[iankronquist]

A tool called cldoc looks pretty nifty. I like it better than Doxygen. Check out the cldoc branch.

[iankronquist]

Largely fixed by #51, but there's always more work to do.

[iankronquist]

So cldoc reports 100% coverage of functions, typedefs, structs, enums, and globals in the headers. I don't really care about self explanatory enum values (COLOR_BLACK) or struct fields (always0). Nonetheless, there are parts of the implementation in the C files which could use some more work. See also #53.

[iankronquist]

We are now back to 0% documentation, somewhat on purpose. I need to fix this.