Using Doxygen with Angband

On Jan 25, 2:22 pm, Andrew Sidwell <takka....RemoveThis@gmail.com> wrote:
> Peter Blake wrote:
> <snip>
> > Having good documentation would be of real benefit to me when trying
> > to grok the code, so I'm wondering which of these options you think is
> > best:
>
> > a) change the comment style throughout
> > b) persuade Doxygen to parse the existing comment style (instructions
> > welcome)
> > c) use another doc-generation tool (recommendations welcome)
<snip>
> Doxygen has its own annoying syntax, which I dislike. (I'm told JavaDoc
> and other similar systems use it too, but I don't code Java or C#.) I
> mean the gunk like @brief, @param etc. Comments are for humans to read,
> not computers; it's better to have a syntax which is both human-readable
> and machine-readable without having to put all these special at-tags
> everywhere. Hence, I would prefer c), but have never found anything
> that fits my requirements. (I'm happy to argue out my case on this one,
> but I think it might the issue of aesthetics comes into it somewhere.)

The argument for using the "gunk" (IMO) gets stronger the more
important it is that the documentation stand separate from the code.
That argument doesn't apply here though.

> As Pete has implied, the current Angband documentation generally a long
> winding mass of (outdated) comments and todos, with nothing much in the
> way of API documentation. I rewrite comments as I go, but it would be
> good to set aside some time just to do a file-by-file rewrite, I suppose.

If we can agree on some parameters (e.g. for style and length of
comments), I'd be interested in helping out with this.

Yours,
Peter
 >> Stay informed about: Using Doxygen with Angband 

Peter Blake wrote:
> (I used to read rgra in the late 90s before life-after-university
> intervened. It's great to see that Angband is still going strong. I
> even recognise one or two posters.)
<snip>
> Having good documentation would be of real benefit to me when trying
> to grok the code, so I'm wondering which of these options you think is
> best:
>
> a) change the comment style throughout
> b) persuade Doxygen to parse the existing comment style (instructions
> welcome)
> c) use another doc-generation tool (recommendations welcome)

I want to standardise on a documentation tool that I don't have to
maintain. I'm OK with writing standard English comments and doing a) --
and have already started doing as much in the development branch. I
would love to get b), but I don't think it's possible.

Doxygen has its own annoying syntax, which I dislike. (I'm told JavaDoc
and other similar systems use it too, but I don't code Java or C#.) I
mean the gunk like @brief, @param etc. Comments are for humans to read,
not computers; it's better to have a syntax which is both human-readable
and machine-readable without having to put all these special at-tags
everywhere. Hence, I would prefer c), but have never found anything
that fits my requirements. (I'm happy to argue out my case on this one,
but I think it might the issue of aesthetics comes into it somewhere.)

As Pete has implied, the current Angband documentation generally a long
winding mass of (outdated) comments and todos, with nothing much in the
way of API documentation. I rewrite comments as I go, but it would be
good to set aside some time just to do a file-by-file rewrite, I suppose.

Andrew Sidwell
http://rephial.org/
 >> Stay informed about: Using Doxygen with Angband 

On 2008-01-25 05:22:06, Andrew Sidwell <takkaria.TakeThisOut@gmail.com> wrote:

> Peter Blake wrote:
> > (I used to read rgra in the late 90s before life-after-university
> > intervened. It's great to see that Angband is still going strong. I
> > even recognise one or two posters.)
>
> > Having good documentation would be of real benefit to me when trying
> > to grok the code, so I'm wondering which of these options you think is
> > best:
> >
> > a) change the comment style throughout
> > b) persuade Doxygen to parse the existing comment style (instructions
> > welcome)
> > c) use another doc-generation tool (recommendations welcome)
>
> I want to standardise on a documentation tool that I don't have to
> maintain. I'm OK with writing standard English comments and doing a) --
> and have already started doing as much in the development branch. I
> would love to get b), but I don't think it's possible.

As I use Doxygen myself for other projects, I wouldn't mind a "minimum common
denominator" to facilitate auto-extraction across several major documentation
tools.

> Doxygen has its own annoying syntax, which I dislike. (I'm told JavaDoc
> and other similar systems use it too, but I don't code Java or C#.) I
> mean the gunk like @brief, @param etc. Comments are for humans to read,
> not computers; it's better to have a syntax which is both human-readable
> and machine-readable without having to put all these special at-tags
> everywhere. Hence, I would prefer c), but have never found anything
> that fits my requirements. (I'm happy to argue out my case on this one,
> but I think it might the issue of aesthetics comes into it somewhere.)

Doxygen's syntax is a lot less annoying than Splint's. I use todo and bug quite
a bit, but haven't gotten into parameter documentation worth anything.

More generally (and this is one of the things that occasionally has me doing
feasibility studies of Yet Another C/C++ Compiler): most of the interesting
things I'd want to do with Doxygen, are advanced-lint things that really should
be automatic compiler warnings (if not errors, but at that point we're talking
about going non-ISO). [More generally, I'd like warnings *whenever* dataflow
indicates assert() or exit(FAILURE) is going to go off.]
 >> Stay informed about: Using Doxygen with Angband 

Peter Blake wrote:
> On Jan 25, 2:22 pm, Andrew Sidwell <takka... RemoveThis @gmail.com> wrote:
>> Peter Blake wrote:
....
>> Doxygen has its own annoying syntax, which I dislike. (I'm told JavaDoc
>> and other similar systems use it too, but I don't code Java or C#.) I
>> mean the gunk like @brief, @param etc. Comments are for humans to read,
>> not computers; it's better to have a syntax which is both human-readable
>> and machine-readable without having to put all these special at-tags
>> everywhere. Hence, I would prefer c), but have never found anything
>> that fits my requirements. (I'm happy to argue out my case on this one,
>> but I think it might the issue of aesthetics comes into it somewhere.)
>
> The argument for using the "gunk" (IMO) gets stronger the more
> important it is that the documentation stand separate from the code.
> That argument doesn't apply here though.

Perhaps. I'm not a professional coder, so I wouldn't know.

>> As Pete has implied, the current Angband documentation generally a long
>> winding mass of (outdated) comments and todos, with nothing much in the
>> way of API documentation. I rewrite comments as I go, but it would be
>> good to set aside some time just to do a file-by-file rewrite, I suppose.
>
> If we can agree on some parameters (e.g. for style and length of
> comments), I'd be interested in helping out with this.

Well, that being the case...

I've been documenting things in the header files at the moment, just
because that's where I tend to look up function definitions. I think
that really we want them in the source files instead, though. The only
problem I can think of with that approach is when source files have
multiple functions with the same name but different ifdefs -- e.g. the
new directory-scanning code (in z-file.c), which uses entirely different
implementations on POSIX and Windows.

For an example of the kind of style I've been using, see:
http://dev.rephial.org/trac/browser/trunk/src/z-file.h
http://dev.rephial.org/trac/browser/trunk/src/z-msg.h

If you want to come up with a list of things that would make comments
fit your ideas of how they should be, we could go from there. I just
tend to write in the style that comes out naturally.

[Note also that the development version of Angband is quite a different
beast when it comes to file organisation to 3.0.9 -- lots of things have
been split out into new files, chiefly with the aim of making the code
easier to maintain and learn.]

At some point, the function declarations should probably be
autogenerated from the .c files, as it's implied they are now, for
consistency's sake.

--
Andrew Sidwell
http://rephial.org/
 >> Stay informed about: Using Doxygen with Angband 

Kenneth 'Bessarion' Boyd wrote:
> As I use Doxygen myself for other projects, I wouldn't mind a "minimum common
> denominator" to facilitate auto-extraction across several major documentation
> tools.

What other major documentation tools do you have in mind?

--
Andrew Sidwell
http://rephial.org/
 >> Stay informed about: Using Doxygen with Angband 

On 2008-01-25 07:40:09, Andrew Sidwell <takkaria.TakeThisOut@gmail.com> wrote:

> Kenneth 'Bessarion' Boyd wrote:
> > As I use Doxygen myself for other projects, I wouldn't mind a "minimum common
> > denominator" to facilitate auto-extraction across several major documentation
> > tools.
>
> What other major documentation tools do you have in mind?

Restricting my attention to ones targeting C/C++ languages, and considering my
bias for best-of-breed tools over swiss army knives:
* Splint, strictly speaking, is an advanced lint based on Larch. That said, it
does just about everything I'd want to properly document function interfaces in
C. [It's not so useful in C++; maybe about a third of the annotations should be
handled by language features that cause compiler errors instead.] It 's pretty
much useless for user documentation.

I would seriously consider Splint for any pure-C project, and am studying it
carefully for other reasons. If you don't want to pollute the C code with its
annotations: it does support external files for documenting function
interfaces.

* Between Doxygen and JavaDoc, a standard for C-like language documentation
generators is shaking out. C comments of the form /** */ are looking very good
for forward compatibility against future unknown tools. This is also
responsible for the @___ conventions. Among the tools based on this comment
convention, I use Doxygen for the call graph identification.

* While RoboDoc is interesting, its formatted comments don't look interoperable
with the other major tools.
 >> Stay informed about: Using Doxygen with Angband 

Andrew Sidwell <takkaria DeleteThis @gmail.com> writes:

> Peter Blake wrote:
> > (I used to read rgra in the late 90s before life-after-university
> > intervened. It's great to see that Angband is still going strong. I
> > even recognise one or two posters.)
> <snip>
> > Having good documentation would be of real benefit to me when trying
> > to grok the code, so I'm wondering which of these options you think is
> > best:
> > a) change the comment style throughout
> > b) persuade Doxygen to parse the existing comment style (instructions
> > welcome)
> > c) use another doc-generation tool (recommendations welcome)
>
> I want to standardise on a documentation tool that I don't have to maintain. I'm OK with writing standard English comments and doing a) --
> and have already started doing as much in the development branch. I would
> love to get b), but I don't think it's possible.
>
> Doxygen has its own annoying syntax, which I dislike. (I'm told JavaDoc and
> other similar systems use it too, but I don't code Java or C#.) I mean the
> gunk like @brief, @param etc. Comments are for humans to read, not computers;
> it's better to have a syntax which is both human-readable and machine-readable
> without having to put all these special at-tags everywhere. Hence, I would
> prefer c), but have never found anything that fits my requirements. (I'm
> happy to argue out my case on this one, but I think it might the issue of
> aesthetics comes into it somewhere.)
>
> As Pete has implied, the current Angband documentation generally a long
> winding mass of (outdated) comments and todos, with nothing much in the way of
> API documentation. I rewrite comments as I go, but it would be good to set
> aside some time just to do a file-by-file rewrite, I suppose.

I just spent time to track down a bug [doing auto-awareness] because, silly
me, I figured k_info[].pval indicated the maximum pval for an object kind.
It turns out that is ignored, and the actual maxima are hard-coded.

I'd rather see initial effort spent generally improving the overall
architecture. Remove magic numbers, fix the flag interface, and reduce the
usage of global variables to begin with. Instead of "s16b pval;" defs
throughout the code, there should be a typedef like "typedef s16 pval_type;"
and then "pval_type pval;" defs throughout the code, so that if some day we
want some other number of bits for pvals it is a single change. It's almost
as if the code is meant as a "don't do this" case study for some coding 101
course.

Oh well, doc really is important, but I just had to vent.


Eddie
 >> Stay informed about: Using Doxygen with Angband 

On 2008-01-25 18:09:44, Eddie Grove <eddiegrove RemoveThis @hotmail.com> wrote:

> It's almost
> as if the code is meant as a "don't do this" case study for some coding 101
> course.

I assume you've seen this:
http://www.web-hits.org/txt/codingunmaintainable.html

Nick.
--
"You are judging by social rules, and finding crime. I am considering an
elemental struggle, and finding no crime, just grim, primeval danger." - The
Midwich Cuckoos, John Wyndham
 >> Stay informed about: Using Doxygen with Angband 

Nick wrote:
> On 2008-01-25 18:09:44, Eddie Grove <eddiegrove.RemoveThis@hotmail.com> wrote:
>
>> It's almost
>> as if the code is meant as a "don't do this" case study for some coding 101
>> course.
>
> I assume you've seen this:
> http://www.web-hits.org/txt/codingunmaintainable.html

A good guide as to what needs to be done with Angband still. I
particularly liked:
: Since global variables are "evil", define a structure to hold all
the things you'd put in globals. Call it something clever like
EverythingYoullEverNeed. Make all functions take a pointer to this
structure (call it handle to confuse things more). This gives the
impression that you're not using global variables, you're accessing
everything through a "handle". Then declare one statically so that all
the code is using the same copy anyway.

That's not too far away from what bits of Angband do.

--
Andrew Sidwell
http://rephial.org/
 >> Stay informed about: Using Doxygen with Angband 

On 2008-01-25, Andrew Sidwell <takkaria.TakeThisOut@gmail.com> wrote:
> Doxygen has its own annoying syntax, which I dislike. (I'm told JavaDoc
> and other similar systems use it too, but I don't code Java or C#.) I
> mean the gunk like @brief, @param etc. Comments are for humans to read,

Use can use different formats for those commands, eg \param rather than @param.
I've doxygen to be minimally intrusive.
 >> Stay informed about: Using Doxygen with Angband 

Andrew Sidwell wrote:
> Peter Blake wrote:
>> Andrew Sidwell wrote:
>>> Peter Blake wrote:
<snip>
>>
>> If we can agree on some parameters (e.g. for style and length of
>> comments), I'd be interested in helping out with this.
>
> Well, that being the case...
>
> I've been documenting things in the header files at the moment, just
> because that's where I tend to look up function definitions. I think
> that really we want them in the source files instead, though. The only
> problem I can think of with that approach is when source files have
> multiple functions with the same name but different ifdefs -- e.g. the
> new directory-scanning code (in z-file.c), which uses entirely different
> implementations on POSIX and Windows.

As long as such functions are clearly commented, I don't see that
being a problem. Or maybe I'm missing something?

> For an example of the kind of style I've been using, see:
> http://dev.rephial.org/trac/browser/trunk/src/z-file.h
> http://dev.rephial.org/trac/browser/trunk/src/z-msg.h
>
> If you want to come up with a list of things that would make comments
> fit your ideas of how they should be, we could go from there. I just
> tend to write in the style that comes out naturally.

I like your use of `-s around every parameter name. Doxygen's
equivalent is \p, which is pretty unreadable.

Here's an example:
/**
* Provides an example of a documentation style.
*
* The purpose of the function (etc.) is explained here, mentioning
* the name and use of every parameter. It returns TRUE if conditions
X
* or Y are met, and FALSE otherwise.
*
* BUG: Brief description of bug. (#12345)
* TODO: Feature to implement. (#54321)
*/

(Having the brief description separated out from the remainder of the
comment means that Doxygen can pull it out without needing @brief
tags.)

And some further stylistic suggestions:
- In brief descriptions of classes and functions, use present tense
(i.e. answer the question "What does this do?" with "It constructs /
edits / calculates / returns...")
- In long descriptions, use passive mood to refer to variables (i.e.
"The variables are normalised." as opposed to "This normalises the
variables.")
- No UK/US spelling preference (i.e. the preference of the first
commenter is adopted for that comment).
- (from "The Elements of Style") "A sentence should contain no
unnecessary words, a paragraph no unnecessary sentences, for the same
reason that a drawing should have no unnecessary lines and a machine
no unnecessary parts. This requires not that the writer make all his
sentences short, or that he avoid all detail and treat his subjects
only in outline, but that every word tell."

How does that sound?

> [Note also that the development version of Angband is quite a different
> beast when it comes to file organisation to 3.0.9 -- lots of things have
> been split out into new files, chiefly with the aim of making the code
> easier to maintain and learn.]

Noted.

I'd also prefer to get rid of some of the joke-ier comments (e.g. on
the forward declare for 'birther' in birth.c - how many people are
going to get it?), but YMMV.

Yours,
Peter
 >> Stay informed about: Using Doxygen with Angband 

Peter Blake wrote:
> Andrew Sidwell wrote:
>> I've been documenting things in the header files at the moment, just
>> because that's where I tend to look up function definitions. I think
>> that really we want them in the source files instead, though. The only
>> problem I can think of with that approach is when source files have
>> multiple functions with the same name but different ifdefs -- e.g. the
>> new directory-scanning code (in z-file.c), which uses entirely different
>> implementations on POSIX and Windows.
>
> As long as such functions are clearly commented, I don't see that
> being a problem. Or maybe I'm missing something?

I just am not sure of how it will confuse doxygen. I'll have to play
and see how that works, but I take it that putting the comments in C
files is the norm. That works OK, because there might be a way to start
autogenerating header files from the C files in that case.

>> For an example of the kind of style I've been using, see:
>> http://dev.rephial.org/trac/browser/trunk/src/z-file.h
>> http://dev.rephial.org/trac/browser/trunk/src/z-msg.h
>>
>> If you want to come up with a list of things that would make comments
>> fit your ideas of how they should be, we could go from there. I just
>> tend to write in the style that comes out naturally.
>
> I like your use of `-s around every parameter name. Doxygen's
> equivalent is \p, which is pretty unreadable.

I needed something to differentiate parameters from quoted text, and it
was the only quote character left.

> Here's an example:
> /**
> * Provides an example of a documentation style.
> *
> * The purpose of the function (etc.) is explained here, mentioning
> * the name and use of every parameter. It returns TRUE if conditions
> X
> * or Y are met, and FALSE otherwise.
> *
> * BUG: Brief description of bug. (#12345)
> * TODO: Feature to implement. (#54321)
> */
>
> (Having the brief description separated out from the remainder of the
> comment means that Doxygen can pull it out without needing @brief
> tags.)

Ah, good, I was hoping there was some way to avoid @brief.

> And some further stylistic suggestions:
> - In brief descriptions of classes and functions, use present tense
> (i.e. answer the question "What does this do?" with "It constructs /
> edits / calculates / returns...")
> - In long descriptions, use passive mood to refer to variables (i.e.
> "The variables are normalised." as opposed to "This normalises the
> variables.")
> - No UK/US spelling preference (i.e. the preference of the first
> commenter is adopted for that comment).
> - (from "The Elements of Style") "A sentence should contain no
> unnecessary words, a paragraph no unnecessary sentences, for the same
> reason that a drawing should have no unnecessary lines and a machine
> no unnecessary parts. This requires not that the writer make all his
> sentences short, or that he avoid all detail and treat his subjects
> only in outline, but that every word tell."
>
> How does that sound?

Thanks, these sound good to me. Replacing XXXs with BUG and TODO will
make it easier to keep track of which bits of code need fixing
(according to Ben, at least...).

I've put these suggestions at http://rephial.org/wiki/CodeDocs for
future reference. I can't imagine anyone disagreeing with these
suggestions, really, either, though perhaps additional customs will
arise over time.

I notice that doxygen uses /** \file Comment text */ to define comments
for files. I think I can deal with that level of pollution.

>> [Note also that the development version of Angband is quite a different
>> beast when it comes to file organisation to 3.0.9 -- lots of things have
>> been split out into new files, chiefly with the aim of making the code
>> easier to maintain and learn.]
>
> Noted.
>
> I'd also prefer to get rid of some of the joke-ier comments (e.g. on
> the forward declare for 'birther' in birth.c - how many people are
> going to get it?), but YMMV.

That one's only been there since just after 3.0.9 was released -- it was
sneaked into an unrelated commit, I believe -- so it should probably be
introduced into at least one public release.

All that said, I'm not sure where to go from here. A file-by-file
approach is probably too much (since the files have so many functions in
them), so I wonder how to best get things converted across. I can
rewrite the comments that are already vaguely styled as above, but
beyond that, I'm not sure.

--
Andrew Sidwell
http://rephial.org/
 >> Stay informed about: Using Doxygen with Angband 

On 2008-01-28 07:56:14, Andrew Sidwell <takkaria.DeleteThis@gmail.com> wrote:

> Peter Blake wrote:
> > Andrew Sidwell wrote:
> >> I've been documenting things in the header files at the moment, just
> >> because that's where I tend to look up function definitions. I think
> >> that really we want them in the source files instead, though. The only
> >> problem I can think of with that approach is when source files have
> >> multiple functions with the same name but different ifdefs -- e.g. the
> >> new directory-scanning code (in z-file.c), which uses entirely different
> >> implementations on POSIX and Windows.

It is probably best to put the documentation outside of the #ifdefs. Doxygen's
inbuilt C preprocessor is fairly limited.

> > As long as such functions are clearly commented, I don't see that
> > being a problem. Or maybe I'm missing something?
>
> I just am not sure of how it will confuse doxygen. I'll have to play
> and see how that works, but I take it that putting the comments in C
> files is the norm. That works OK, because there might be a way to start
> autogenerating header files from the C files in that case.

Given a choice, Doxygen prefers the header file for brief descriptions and the c
files for the detailed description. It otherwise seems confusion-resistant.

> > I like your use of `-s around every parameter name. Doxygen's
> > equivalent is p, which is pretty unreadable.

param is more readable, should a parameter actually need documenting explicitly.
You don't have to take the shortcut just because you can.

Aside: took a partial pass at "Doxygenating" Zaiband. (With intent to arrange
for automatic generation of HTML help files, although I'm having problems
figuring out the commands for that.)
* You would be fairly safe assuming most comments right before a function are
documentation comments suitable for /** */ conversion.
* z-term.h/c should be fairly high on the list, or at least the term_win and
term structs. My test conversion of documenting the term_win and term structs
by field de-bloated z-term.h noticeably.
* The pollution from return is a grammar error. There's very little difference
between "Returns TRUE if ..." and "return TRUE if ..."
 >> Stay informed about: Using Doxygen with Angband