On 13 January 2011 12:28, Jude <bookofj...@gmail.com> wrote: > Our code has basically little or no documentation; a lot of the > documentation we have is outdated or incorrect.
I beg to differ with that. It's true that _some_ areas are undocumented (mostly those no one really understands) and that in some other places the documentation is incomplete. However, neither of these would be solved by adding an automatic documentation system alone. Developers will still need to add the necessary comments on their own. (Actually, I'm surprised there's no "Please document your code!" already in the coding conventions. That seems so basic an instruction.) As I see it, switching to doxygen (or something similar) will have a different sort of advantage, namely that as a coder (or source diver), you won't have to dig through the source itself to find out how to call a function and what the parameters are supposed to mean, but instead will be able to look it directly up in the documentation. Seeing how, at any given time, I usually have about 8 different files open just for checking function syntax, that's certainly something I'd love to have. :D Doxygen is the only documentation system I have any sort of experience with, and as far as I remember the syntax is extremely straightforward and the generated doc easy to read. Johanna ------------------------------------------------------------------------------ Protect Your Site and Customers from Malware Attacks Learn about various malware tactics and how to avoid them. Understand malware threats, the impact they can have on your business, and how you can protect your company and customers by using code signing. http://p.sf.net/sfu/oracle-sfdevnl _______________________________________________ Crawl-ref-discuss mailing list Crawl-ref-discuss@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/crawl-ref-discuss
