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?image missing /media/kunena/emoticons/w00t.png
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).
What would be really useful (including to me) would be a flowchart that tracks a simple G-code command (like coolant-flood) from the Interpreter to the HAL pin.
There are so many layers and abstractions (not all of which seem necessary)
Oh, and a clear indication where the switch to realtime happens in this flow would be helpful too.
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.
What would be really useful (including to me) would be a flowchart that tracks a simple G-code command (like coolant-flood) from the Interpreter to the HAL pin.
There are so many layers and abstractions (not all of which seem necessary)
Oh, and a clear indication where the switch to realtime happens in this flow would be helpful too.
Yes, the biggest hurdle when working on an issue is figuring out which parts of the source code are involved in the first place. I have used Sourcetrail and Doxigen but what I really lack is a bigger picture.
- what happens in case of a program abort
- what is involved when the feed override value changes
....
That probably is the greatest loss when a long term contributor retires from the project.
Documentation of such trans code 'paths' would also likely be less prone to become outdated as the source code evolves.
