I've the idea that writing in some detail about the initialization process will help those new to flightgear's code in some way. My feeling is that following the initialization process is a good way to become familiar with the overall structure of flightear's code.
The subsystems are a big part of the initialization process. Would it be useful to state the main responsibilities of each subsystem, accompanied by some kind of explanation of it's context in the overall application and to identify important data and control flows into and out of each subsystem?
What I'd like to write is high level guide to what code to read and in what order. I'm still unsure what will need explaining and what will not. I'd like to avoid the useless style of documentation that states the obvious.
It will definitely not be a "complete reference", "api documentation", or anything like that. ]
Until it's complete, reviewed and fact checked by others, I'll keep it under []
The end result should be that the writer and a reader has
- read or skimmed a fair bit of code
- knows were the important bits of flightgear live
- has a sense of what is dependent on what
- knows what the various parts do and how they interact with the system as a whole.
- has the whole picture, not just the puzzle piece they're interested in.
In short they're ready to chase bugs or write new code. Which is exactly why I'm writing this to begin with.
Works in progress