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

[James Dennett]

On Tue, Jun 12, 2012 at 11:59 PM, Sean Silva <silvas at purdue.edu> wrote:
> I'm kind of against the backslash-escaping because it makes the comments
> uglier to read in the source.

That seems like a policy choice to me -- are these Doxygen comments or not?

My impression is that the intent is that they produce good output from
Doxygen, with the fact that they can be read in the source code being
desirable but not their defining characteristic.

> What does doxygen do with @ and # anyway? Is
> there a way to tell doxygen "don't give @ and # the special meaning"?

@ can be used almost interchangeably with \ in Doxygen comments -- and
is fairly widely used in the Doxygen comments in Clang.

>From http://www.stack.nl/~dimitri/doxygen/commands.html: "All commands
in the documentation start with a backslash (\) or an at-sign (@). If
you prefer you can replace all commands starting with a backslash
below by their counterparts that start with an at-sign."

I'm not aware of a way to disable @ or # processing in Doxygen, and a
quick search of its documentation didn't turn anything up.

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

Fair enough.  I have reasons to disagree, but won't belabor them here.

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

I'm not aware of what work has been done there; certainly it would be
desirable to replace Doxygen's C and C++ parsers with Clang's.

> 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'm sure I can find someone willing to police this ;-)

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

Thanks for doing so.

-- James