A flowchart paranoid (a story about source code documentation)

Hello everyone.

I've always been very curious about how LinuxCNC code works, and I participated in translating the documentation into Spanish when it was at version 2.8. Now I'm looking for opinions in a forum about a need some of us might have (I suppose): documentation of the source code itself.

I love images. A flowchart is a treasure for me. Yes, I know: code is the best documentation... but sometimes it's a real headache (we all know that, right?).

That said, let's get down to business!

I've prepared the PDF attached to this post. First of all, apologies: some of it is in Spanish (mainly the descriptions), but that doesn't obscure the general idea.

The document relates to the halcmd_completion.c file and is just an example. It only took me half a day to prepare, and the flowcharts haven't been proofread. I insist: I'm asking for your opinions on my vision, not for technical corrections.

This isn't the time to discuss the file itself, but rather to share my idea for documentation. I believe any "novice LinuxCNC coder" can find guidance with this type of "document".

I'm also aware that this is a user forum, not a developer meeting place, but... what about "high-end" users?  

Thanks in advance for your comments.
J.M. Garcia a.k.a. Abu

I believe any "novice LinuxCNC coder" can find guidance with this type of "document". I'm also aware that this is a user forum, not a developer meeting place, but... what about "high-end" users

I like the the idea. To me it looks a bit cleaner than I get from doxygen (or may be I do not know how to use it). I am not a developer but I am constantly digging thru source code to see what makes things work (or not).

Its very difficult to deal with a 4.0 metre long page if you want a hard copy (which is the whole point of PDF). What printer does that? The page width of 210mm is the exact width of an A4 page. Is there any chance you could add page breaks  say every 297mm (you may need to allow for page margins too which is all supported in PDF.