I can't get no

 ... satisfaction documentation. I mean, useful, unobtrusive, easy to write (and maintain!).

Last week I finished documenting stable API items, which are almost all of them. And yet, as a saying goes "careful with what you're wishing for, you might get it". So, I got typed myself old-school Doxygen documentation, sprinkled all over the code with firehose, so much so that now it's almost impossible to find anything at a glance. Sure, MS Visual Code has "fold comments" + "unfold all" keybinds, which helps, it makes code workable; but so sorry for anyone opening sources in common editor.

So, I started thinking to move documentation into a manually written RSTs, and building it with Sphinx. Overhead would be great, if everything needs to be documented, but maybe not. For most part, things needs just mentioning in the docs, not a short novel how to pass a pointer, and get length of a linked list. Most interesting bits (about ownership and borrows) are already documented in a common pages. And, stable API doesn't change all that often, so this might actually work. 

Only real problem I see is when things do change (and they will), how to reliably find what has been changed. Possible solution would be to diligently document such a cases immediately after they have been done, but don't kid ourselves, it ain't gonna work, it never does. So, I'll need some sort of an automatic copying from C declarations into RSTs, with some light editing (adding indentation to code, and introduction at start of a files). This way things that need mentioning are covered by automatic copy, and things that do need proper documentation are covered in a separate place, by hand-crafted novel. 

Problem with copying is that links to and indexing of functions, structs, enums are not generated. That would require parsing C properly, which is not a trivial task. Since I don't need comments for what is essentially still a copying, with benefits, I'll try to use pycparser, and see how it goes.

So, back to the side-questing, I guess, ... again.

Edit: I tried pycparser, not user-friendly, needs a lot of pampering, and still I couldn't get it to work. I then tried clang Python bindings, doesn't have intuitive API, and without any meaningful documentation, I decided to give up.

Experience taught me to limit time spent tinkering with someone else's project, based on that projects worth to me. If it doesn't work by then, I'm not wasting my time any more, especially if there are no signs of any real progress. 

So, Doxygen it is.