Tools where you embed the documentation in the source file cause the developer to write skimpy incomplete documentation. Why so? The developer fears that the more docs he adds to the source file, the more crap gets in, near, above, or below his algorithms!
Embedded documentation tools encourage the developer to write poor, skimpy, and terse help notes for the project.
Embedded documentation in the source file is a short term instant gratification.
If the source comments ever gets updated.. you have to recompile the docs! With tools like lufdoc you can add notes to the docs at any time without recompiling the documentation for each minor or major change you make to the docs.
Developers should make comments on the sources in the sources.. but the end user documentation should be much more bulky and separate from developer comments. For example the documentation should contain plenty of examples and verbose explanations of what a function does and does not do.
The more crap you add to the source file with embedded documentation, the more you fear adding more crap.. since your source file is so full of crap.
All the projects that have used embedded documentation usually end up with skimpy terse documentation.. such as the Synapse project, KOL project, etc.
What happens is Synapse opens up a Wiki with verbose documentation in the wiki.. and the actual documentation becomes fragmented since you have some of the docs in the wiki, some in the source file, some on the mailing list, etc. The Wiki contains some docs, and the embedded PasDocs contain some other docs. Instead the documentation should be all in one single place like with Lufdoc where even the reference guide and API guide are together in one area at one consistent website.
I'm not arguing that projects which use lufdoc/fpdoc are always going to contain good verbose documentation.. because good verbose documentation takes lots of time to write. I'm arguing that tools like PasDoc and embedded documentation systems like what KOL uses basically limit the project for growth. The source file cannot possibly grow as big as the documentation grows.
That is, if you have good lengthy complete documentation.. the docs will never fit into the source file.. so don't try it. You will just have a source file so unmaintainable and huge that you will want to cry.. and you will never want to look into it.
On the other hand, if you believe in poor terse documentation.. then embedded docs will work for a while, and your project will still have some limited potential.
|
