Our code has basically little or no documentation; a lot of the documentation we have is outdated or incorrect. Thus, I think we should start a deliberate documentation attempt. The following steps are involved:
1. If you add a new function, please document it. 2. If you edit a function and understand how it works, and the function doesn't have documentation, please document it. 3. Large functions (see mon-act.cc, eek) can and should be split into smaller functions by those who understand them. If you do this, please document the functions! Obviously, this doesn't address the following issues. 1. How do we document them? 2. What do we do about the Lua bindings? Point 2 is a point for discussion at another time. With regards to point 1, after discussing it a little bit in ##crawl-dev, I think the best initial option is to use Doxygen. Some people have used it before, others have not. I myself fall into the latter category, but after having a quick look at the documentation, I feel that it is easy to pick up and use. <http://www-scf.usc.edu/~peterchd/doxygen/> is an extremely concise introduction with an explanation of the syntax. The Wikipedia article <http://en.wikipedia.org/wiki/Doxygen> also has some explanations of the system. I believe that it is better to start documenting code now with Doxygen and thus have the comments in place, regardless of whether or not we actually decide to use Doxygen. If we decide to use something else, then we already have comments in place and can adjust these as necessary. Barring any significant reasons against it, I will shortly (likely this weekend barring further catastrophic flooding) create an initial configuration file for doxygen and begin commenting functions that I myself have created or know quite well. We should probably come up with a specific documentation style and note it in our style guideline, however I do not believe that there are many different ways of writing the comments, and the most important thing now is getting the information in there. Comments, etc, welcome. -J ------------------------------------------------------------------------------ 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
