This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
[v3] update doxygen markup rules
- From: Benjamin Kosnik <bkoz at redhat dot com>
- To: gcc-patches at gcc dot gnu dot org, libstdc++ at gcc dot gnu dot org
- Date: Wed, 17 Feb 2010 14:34:40 -0800
- Subject: [v3] update doxygen markup rules
Follow up to man page work.
tested x86-64/linux
-benjamin
2010-02-17 Benjamin Kosnik <bkoz@redhat.com>
* doc/xml/manual/appendix_contributing.xml: Update markup rules
for quoting and functions.
Index: doc/xml/manual/appendix_contributing.xml
===================================================================
--- doc/xml/manual/appendix_contributing.xml (revision 156837)
+++ doc/xml/manual/appendix_contributing.xml (working copy)
@@ -1002,31 +1002,40 @@
</para>
<para>
- These points accompany the first list in section 3.1 of the
- Doxygen manual:
+ Some commentary to accompany
+ the first list in the <ulink url="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special
+ Documentation Blocks</ulink> section of
+ the Doxygen manual:
</para>
<orderedlist>
- <listitem><para>Use the Javadoc style...</para></listitem>
<listitem>
+ <para>For longer comments, use the Javadoc style...</para>
+ </listitem>
+
+ <listitem>
<para>
...not the Qt style. The intermediate *'s are preferred.
</para>
</listitem>
- <listitem>
+
+ <listitem>
<para>
Use the triple-slash style only for one-line comments (the
- <quote>brief</quote> mode). Very recent versions of Doxygen permit
- full-mode comments in triple-slash blocks, but the
- formatting still comes out wonky.
+ <quote>brief</quote> mode).
</para>
</listitem>
+
<listitem>
<para>
This is disgusting. Don't do this.
</para>
</listitem>
</orderedlist>
+
+ <para>
+ Some specific guidelines:
+ </para>
<para>
Use the @-style of commands, not the !-style. Please be
@@ -1051,6 +1060,89 @@
(Examples of all these abound in the present code.)
</para>
+ <para>
+ Complicated math functions should use the multi-line
+ format. An example from <filename>random.h</filename>:
+ </para>
+
+ <para>
+<literallayout>
+ /**
+ * @brief A model of a linear congruential random number generator.
+ *
+ * @f[
+ * x_{i+1}\leftarrow(ax_{i} + c) \bmod m
+ * @f]
+ */
+</literallayout>
+ </para>
+
+ <para>
+ Be careful about using certain, special characters when
+ writing Doxygen comments. Single and double quotes, and
+ separators in filenames are two common trouble spots. When in
+ doubt, consult the following table.
+ </para>
+
+<table frame='all'>
+<title>HTML to Doxygen markup comparison</title>
+<tgroup cols='2' align='left' colsep='1' rowsep='1'>
+<colspec colname='c1'></colspec>
+<colspec colname='c2'></colspec>
+
+ <thead>
+ <row>
+ <entry>HTML</entry>
+ <entry>Doxygen</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>\</entry>
+ <entry>\\</entry>
+ </row>
+
+ <row>
+ <entry>"</entry>
+ <entry>\"</entry>
+ </row>
+
+ <row>
+ <entry>'</entry>
+ <entry>\'</entry>
+ </row>
+
+ <row>
+ <entry><i></entry>
+ <entry>@a word</entry>
+ </row>
+
+ <row>
+ <entry><b></entry>
+ <entry>@b word</entry>
+ </row>
+
+ <row>
+ <entry><code></entry>
+ <entry>@c word</entry>
+ </row>
+
+ <row>
+ <entry><em></entry>
+ <entry>@a word</entry>
+ </row>
+
+ <row>
+ <entry><em></entry>
+ <entry><em>two words or more</em></entry>
+ </row>
+ </tbody>
+
+</tgroup>
+</table>
+
+
</sect3>
</sect2>
@@ -1242,7 +1334,7 @@
<thead>
<row>
<entry>HTML</entry>
- <entry>XML</entry>
+ <entry>Docbook</entry>
</row>
</thead>
@@ -1374,6 +1466,7 @@
<entry>
<para><filename class="headerfile">ctype.h</filename></para>
<para><filename class="directory">/home/gcc/build</filename></para>
+ <para><filename class="libraryfile">libstdc++.so</filename></para>
</entry>
</row>
</tbody>