No!, NO!, no SEPARATE documentation.

Sorry, this is a pet peevee,

Every time I have seen a "separate document" describing software it has been out of synch with the actual code. I can not count how many times I have been led astray by documentation that was "almost" correct. I have learned not to read, beyond a glance, separate documents, because they are close enough to make you believe the information which may and may not be correct. If anything need to be documented do it IN THE SOURCE close to what is being documented. This serves several purposes: 1) If the developer see the documentation when working on the code (same screen) (s)he is more likely to "remember" to update the documentation. 2) If there is a disrepancy, the fact of same screen will make seing a mismatch more likely. 3) The update of documentation and code takes place in the same file and thus the documentation update will take place in the current version, not by mistake on some other file with similar contents. I have, on occasion, made .h files with one structure in them in order to have pages and pages of documentation with a small amount of code.

Have fun with one file

Erik