From: Peter Moulder <Peter.Moulder@in...> - 2004-09-05 15:54:49
I said that there were two issues with doxygen usage to be discussed,
but this second one is so minor that actually I don't think we need
discuss it, and I wouldn't be writing this if I hadn't said that I
would :) .
When documenting the requirements or guarantees of a function, or the
invariants of class/struct instance variables, it's common to use
operators from mathematics, whether comparison relations (>=3D, !=
boolean operators (and, or, not, maybe logical implication), set
operators (\in, \subseteq, union, intersection), or quantifiers (fora=
Sometimes one would prefer to differentiate between operator!=3D and
mathematical/abstract inequality (e.g. for NaN or for glib data
structures commonly referred to with pointers). Similarly, one may w=
to use the easier-to-reason-with commutative mathematical and/or
operators instead of C/C++'s short-circuiting &&/|| (or `\&\&', to us=
In javadoc, which I'm more accustomed to, the natural solution is to =
HTML character entity references (`∧', `∈', `≥' etc.) --
partly because HTML supports them, and partly because the alternative
escaped representations (`&&', `>=3D') are worse.
However, doxygen doesn't currently accept many of these -- see
which also discusses alternatives.
Unlike HTML/JavaDoc, Doxygen does allows backslash to be used for
escaping, which eases things a little.
Probably for the moment we'll stick with backslash escaping or keepin=
the words in the generated documentation rather that using symbols. =
an advantage that people are more likely to understand
forall/exists/&&/|| than the corresponding symbols =E2=88=80/=E2=88=
A, backwards E, upside-down v, right-way-up v).