The DCSS source is woefully undocumented, making edits difficult, even for
capable programmers who are looking at areas they're not
specifically familiar with. I haven't worked with doxygen either, and while
some of the commenting styles aren't particularly appealing, the syntax
itself is fairly straightforward, I think.
The wikipedia entry for Doxygen has some examples of different styles of C++
comments. We should probably agree on a standard and stick to it (as well as
add it to the style guideline).
http://en.wikipedia.org/wiki/Doxygen
I don't know if there's a difference in how Doxy treats both ! and @,
though they seem to be used interchangably, I much prefer @ symbols for
identifying parameters, sections, etc. in the documentation. They're much
more visible than exclamation points. I also rather like the two-star
notation that seems to have fallen into favor (or may be required?) in the
Wikipedia Doxy examples.
Regards,
Robert Burnham
On Thu, Jan 13, 2011 at 5:28 AM, Jude <bookofj...@gmail.com> wrote:
> 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
>
------------------------------------------------------------------------------
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
