git
/
gcc
mirror of git://gcc.gnu.org/git/gcc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

appendix_contributing.xml: Update markup rules for quoting and functions. 

2010-02-17  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/appendix_contributing.xml: Update markup rules
	for quoting and functions.

From-SVN: r156838
This commit is contained in:
Benjamin Kosnik 2010-02-17 22:31:19 +00:00 committed by Benjamin Kosnik
parent 2a5f4935e8
commit af14c87be9
2 changed files with 106 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
libstdc++-v3/ChangeLog
View File

@ -1,3 +1,8 @@
2010-02-17 Benjamin Kosnik <bkoz@redhat.com>
* doc/xml/manual/appendix_contributing.xml: Update markup rules
for quoting and functions.
2010-02-17 Chris Jefferson <chris@bubblescope.net> 2010-02-17 Chris Jefferson <chris@bubblescope.net>
* include/bits/locale_facets.h (__convert_to_v): Add empty * include/bits/locale_facets.h (__convert_to_v): Add empty

109
libstdc++-v3/doc/xml/manual/appendix_contributing.xml
View File

@ -1002,31 +1002,40 @@ indicate a place that may require attention for multi-thread safety.
</para> </para>
<para> <para>
These points accompany the first list in section 3.1 of the Some commentary to accompany
Doxygen manual: 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> </para>
<orderedlist> <orderedlist>
<listitem><para>Use the Javadoc style...</para></listitem> <listitem>
<para>For longer comments, use the Javadoc style...</para>
</listitem>
<listitem> <listitem>
<para> <para>
...not the Qt style. The intermediate *'s are preferred. ...not the Qt style. The intermediate *'s are preferred.
</para> </para>
</listitem> </listitem>
<listitem>
<listitem>
<para> <para>
Use the triple-slash style only for one-line comments (the Use the triple-slash style only for one-line comments (the
<quote>brief</quote> mode). Very recent versions of Doxygen permit <quote>brief</quote> mode).
full-mode comments in triple-slash blocks, but the
formatting still comes out wonky.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
This is disgusting. Don't do this. This is disgusting. Don't do this.
</para> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>
<para>
Some specific guidelines:
</para>
<para> <para>
Use the @-style of commands, not the !-style. Please be Use the @-style of commands, not the !-style. Please be
@ -1051,6 +1060,89 @@ indicate a place that may require attention for multi-thread safety.
(Examples of all these abound in the present code.) (Examples of all these abound in the present code.)
</para> </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>&quot;</entry>
<entry>\"</entry>
</row>
<row>
<entry>&apos;</entry>
<entry>\'</entry>
</row>
<row>
<entry>&lt;i&gt;</entry>
<entry>@a word</entry>
</row>
<row>
<entry>&lt;b&gt;</entry>
<entry>@b word</entry>
</row>
<row>
<entry>&lt;code&gt;</entry>
<entry>@c word</entry>
</row>
<row>
<entry>&lt;em&gt;</entry>
<entry>@a word</entry>
</row>
<row>
<entry>&lt;em&gt;</entry>
<entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3> </sect3>
</sect2> </sect2>
@ -1242,7 +1334,7 @@ table below.
<thead> <thead>
<row> <row>
<entry>HTML</entry> <entry>HTML</entry>
<entry>XML</entry> <entry>Docbook</entry>
</row> </row>
</thead> </thead>
@ -1374,6 +1466,7 @@ table below.
<entry> <entry>
<para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para> <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
<para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para> <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
<para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
</entry> </entry>
</row> </row>
</tbody> </tbody>