On Fri, Jan 14, 2011 at 8:15 PM, Johanna Ploog <[email protected]> wrote: > 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
Yes, true! Mostly whenever I try to fix something that I've not experienced before, I find myself looking through various things trying to find previous calls, etc, to work out exactly what does what. > 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.) This is definitely essential. Are there any objections to putting that into the convention now? > 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. I generated a version locally and found that it even included a JavaScript search engine for the code! That is awesome on so many levels. Napkin is currently hosting a "bare" version of what the documentation would look like. Were there actually documentation, it would be even better, but here's a quick example will call graphs enabled; http://crawl.develz.org/doxygen -Jude ------------------------------------------------------------------------------ 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 [email protected] https://lists.sourceforge.net/lists/listinfo/crawl-ref-discuss
