Still barefooted

I had honest intention to start documenting my code. Not that fundamentals are easy to forget, but some subtle points are, and as a saying goes: devil is in the detail. It's also easier to document something when you just finished working on it, than some weeks, or months, later. Best way to do it is to have documenting comments right in front of a function, struct, ... Then, when you change something, you immediately change accompanying comment, et voilà! ... documentation is always in-sync with the code.

Even though I do need doc-gen to pull documentation from code, I'd also like to have freedom to organize it around manually written pages, since it's not that only libcrochess needs documenting, but also Python code to generate images for the book, console application, etc., and having only one documentation folder for the whole project makes it easier to find what you're looking for. Also, doc-gen has to cover not only preferred (usually, its own implementation) language, but also others, and competently so.

As is with proverbial shoemaker (who always have the worst shoes), documentation generators are not up to the task, they are either auto-generated variety (Doxygen), or hands-free LaTeX-lite (Sphinx), but can't do both. Documentation generated by Doxygen leaves quite a bit to desire, especially if you're looking at PDF. Sphinx is better in that regard, except it does not pull comments from code. Sure, it does have autodoc extension for Python, but not for C.

So, how about external extensions? More shoes, worst shoes ever! wurfapi, gasp, breathe, exhale all depend on both Sphinx and Doxygen. Hard, hard  pass. And if you don't know why, I feel so sorry for you.

Oki, whaddabout hawkmoth? Well, first of, it does not generate anything for items which are not actually commented(!?). When doc-comment is written in a header file, function is documented correctly, with correct parameter types (enums, in my case). If the same comment is moved over to source file, enum is converted into an int. I'm assuming this is clang preprocessing and/or  compiling .c file into an AST, but still, it's not exactly correct, and no ref link to type is generated. There are also some open issues, which include typedef, which I do use, thank you very much. Given that some issues are open for 2+ years, I'd say that developers have priorities somewhere else (can't blame them, though).

So, I started thinking, if there is no appropriate tool, roll your own. Lets start from hawkmoth, this time as a standalone tool, parse C and comments, and output reST into Sphinx sources folder, good? Good. Not comfortable with using clang though, if it sterilizes enums in C sources, what else would be missing? Can we have C parser, in Python? Sure, there is pycparser. Except for one little detail. From pycparser documentation: "In order to be compilable, C code must be preprocessed by the C preprocessor - cpp. cpp handles preprocessing directives like #include and #define, removes comments, ...". Fantastic! Also, totally useless for documenting code.

Then there is redhawk, for navigating ASTs. Catch? Well, its dependency is pycparser, which means it too doesn't know about comments. At this stage I started thinking about my own, proper C parser, which can gracefully handle comments, mixed from headers and sources. The thing is, that is not a small project, one can easily spend 6 months, or more, and still not cover some fringe cases.

And, here I am, wandering around like a Yeti, still barefooted.