[OpenAFS-devel] openafs 1.5 weirdness

[Simon Wilkinson]

>
> 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 @{ @}.

That's one of the differences between normal and Qt style comments. I  
suspect that you're correct that we should have opening braces too -  
I'm sure a patch to add them would be gratefully received!

> 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.

Doxygen can document a wide variety of different languages - it does  
have significant use in the C++ space, but there are many projects  
using it for inline C documentation.

> 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! */

Ultimately, all that has happened here is that someone has gone  
through (at the Obio Hackathon, IIRC) and converted the existing  
comments into doxygen style. If there are errors that you spot in  
those comments, patches to correct the errors would be the best way to  
resolve this.

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

Again, I'm pretty sure that there would be no problem getting a patch  
that introduces opening braces applied.

S.