[OpenAFS-devel] openafs 1.5 weirdness

[Marcus Watts]

> Date:    Sat, 09 May 2009 07:35:59 BST
> To:      Marcus Watts <mdw@umich.edu>
> cc:      openafs-devel@openafs.org
> From:    Simon Wilkinson <sxw@inf.ed.ac.uk>
> Subject: Re: [OpenAFS-devel] openafs 1.5 weirdness
> 
> On 9 May 2009, at 04:13, Marcus Watts wrote:
> >
> > Somebody thought this might be doxygen -- but I can't find this
> > string sequence in a quick glance at its online doc, or "/*!< "...
> > Also there don't appear to be doxygen make rules, or a Doxyfile
> > configuration file in the openafs source.
> 
> It's doxygen. It terminates a group of related items. See the doxygen  
> manual for details, and note that we are using Qt style comments.
> 
> Also, the cvs commit message in which these changes landed says ...
> 
> ----------------------------
> revision 1.24
> date: 2008/11/21 07:09:43;  author: shadow;  state: Exp;  lines: +144  
> -108
> DELTA ubik-doxygen-20081121
> AUTHOR axisofentropy@gmail.com
> LICENSE IPL10
> FIXES 123681
> 
> restyle comments in ubik to be doxygen qt-style
> 
> S.
> 

According to the doxygen documentation, there should be a \{ to
match that \}.  Or at least, I think that's what it says.
It actually talks about @{ @}.

doxygen also seems fairly c++ centric.  When I run ubik through it,
I get a very nice description of a "class" called "ubik_hdr", which is
all well & nice, except it ain't true.

I know that in the java world, javadoc is pretty much the rule.
But there are a lot of things about the java language that make
javadoc useful, that aren't nearly so true in C.  Worse yet, well,
here is a good example of why bottom-up documentation design might not be ideal:
#define USER_SERVICE_ID     52  /*!< Since most applications use same port! */

The main reason this annoys me though, is that I use % pretty religiously in
vi.  Unmatched }'s make me unhappy.

				-Marcus Watts