[cfe-commits] PATCH: Fix another bunch of Doxygen-formatting gremlins

[Sean Silva]

I'm kind of against the backslash-escaping because it makes the comments
uglier to read in the source. What does doxygen do with @ and # anyway? Is
there a way to tell doxygen "don't give @ and # the special meaning"?

There's a balance between uglier comments in-source and uglier docs in
doxygen. Overall, I think that the source, which is "how the programmer
intended" in a sense, should be given preferential treatment. Also,
considering that a clang-based doxygen replacement is in the works
(although it has been in the works for a long time already; I'm not holding
my breath), it might be bearable to live with doxygen's deficiencies in
this regard until the replacement occurs.

Another thing to consider is that if programmer awareness of this isn't
raised, then all of these changes are "going against the grain" of new
comments, and will suffer a kind of "rot" in that respect.

I don't feel too strongly about this, but just thought I'd chip in my 2
cents.

--Sean Silva

On Tue, Jun 12, 2012 at 4:57 PM, James Dennett <jdennett at google.com> wrote:

> I'll commit this in the next day or two if there are no objections;
> this is sent in case anyone somehow feels that this is a bad approach
> to fixing up Clang's documentation, or can spot any bad edits.  The
> diff touches comments only.
>
> This reduces the number of warnings generated by Doxygen by about 100
> (roughly 10%).  Issues addressed:
> (1) Primarily, backslash-escaped "@foo" and "#bah" in Doxygen comments
> when they're not supposed to be Doxygen commands or links, and
> similarly for "<baz>" when it's not intended as as HTML tag;
> (2) Changed some \t commands (which don't exist) to \c ("to refer to a
> word of code", as the Doxygen manual says);
> (3) \precondition becomes \pre;
> (4) When touching comments, deleted a couple of spurious spaces in them;
> (5) Changed some \n and \r to \\n and \\r;
> (6) Fixed one tiny typo: #pragms -> #pragma.
>
> TIA for any comments.
>
> -- James
>
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20120612/c154dd46/attachment.html>