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 <[email protected]> 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 > [email protected] > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits > >
_______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
