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"?<div>
<br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>I don't feel too strongly about this, but just thought I'd chip in my 2 cents.</div><div><br></div><div>--Sean Silva</div><div><br><div class="gmail_quote">On Tue, Jun 12, 2012 at 4:57 PM, James Dennett <span dir="ltr"><<a href="mailto:jdennett@google.com" target="_blank">jdennett@google.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I'll commit this in the next day or two if there are no objections;<br>
this is sent in case anyone somehow feels that this is a bad approach<br>
to fixing up Clang's documentation, or can spot any bad edits.  The<br>
diff touches comments only.<br>
<br>
This reduces the number of warnings generated by Doxygen by about 100<br>
(roughly 10%).  Issues addressed:<br>
(1) Primarily, backslash-escaped "@foo" and "#bah" in Doxygen comments<br>
when they're not supposed to be Doxygen commands or links, and<br>
similarly for "<baz>" when it's not intended as as HTML tag;<br>
(2) Changed some \t commands (which don't exist) to \c ("to refer to a<br>
word of code", as the Doxygen manual says);<br>
(3) \precondition becomes \pre;<br>
(4) When touching comments, deleted a couple of spurious spaces in them;<br>
(5) Changed some \n and \r to \\n and \\r;<br>
(6) Fixed one tiny typo: #pragms -> #pragma.<br>
<br>
TIA for any comments.<br>
<span class="HOEnZb"><font color="#888888"><br>
-- James<br>
</font></span><br>_______________________________________________<br>
cfe-commits mailing list<br>
<a href="mailto:cfe-commits@cs.uiuc.edu">cfe-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits</a><br>
<br></blockquote></div><br></div>