This is the mail archive of the libstdc++@gcc.gnu.org mailing list for the libstdc++ project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[libstdc++] doxygen style guide


By popular demand.  The how-to-write part of the index page is split out
into its own style guide, and expanded.  Doing so left the index page with
nothing but the short list of links immediately followed by the long list
of links, so we can remove the short list as well.

I'll be generating and uploading new pages shortly, which will contain
Jerry's recent additions.


2003-07-16  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/mainpage.html:  Move building/writing instructions...
	* docs/doxygen/guide.html:  ...to here.  New file.


Index: docs/doxygen/guide.html
===================================================================
RCS file: docs/doxygen/guide.html
diff -N docs/doxygen/guide.html
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ docs/doxygen/guide.html	16 Jul 2003 23:58:49 -0000
@@ -0,0 +1,107 @@
+<!DOCTYPE html
+          PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <title>Build and Writing Guide for libstdc++-v3 Doxygen</title>
+  <link href="style.css" rel="stylesheet" type="text/css">
+</head>
+
+<body bgcolor="#ffffff">
+
+<h1>libstdc++-v3 Source Documentation</h1>
+
+<p>This file is docs/doxygen/guide.html in the libstdc++-v3 source tree.  It
+   is not included in the generated pages (no real point to doing that).
+</p>
+
+<ul>
+ <li><a href="#creating">Creating the pages</a></li>
+ <li><a href="#writing">Writing the markup</a></li>
+</ul>
+
+<hr />
+
+<a name="creating"><h2>Creating the pages</h2></a>
+<p>The Makefile rules <code>'make doxygen'</code>,
+   <code>'make doxygen-maint'</code>, and <code>'make doxygen-man'</code>
+   in the libstdc++-v3 build directory generate the user-level HTML docs, the
+   maintainer-level HTML docs, and the man pages, respectively.  Prerequisite
+   tools are
+   <a href="http://www.doxygen.org/";>
+   <!-- snagged from the generated page -->
+   <img src="doxygen.png" alt="Doxygen" align=center border=0 width=110 height=53>
+   </a>, a working version of <code>g++</code> somewhere in the PATH, and
+   the <a href="http://www.gnu.org/software/coreutils/";>GNU coreutils</a>.
+   (g++ is used to build a program which manipulates man pages.  GNU versions
+   of find, xargs, and possibly sed and grep are used, just because the GNU
+   versions make things very easy.)
+</p>
+
+<p>Careful observers will see that the Makefile rules simply call a script
+   from the source tree, <code>run_doxygen</code>, which does the actual work
+   of running Doxygen and then (most importantly) massaging the output files.
+   If for some reason you prefer to not go through the Makefile, you can call
+   this script directly.  (Start by passing <code>'--help'</code>.)
+</p>
+
+<p>If you wish to tweak the Doxygen settings, do so by editing
+   <code>docs/doxygen/user.cfg.in</code>.  Notes to v3-hackers are written in
+   triple-# comments.
+</p>
+
+<a name="writing"><h2>Writing the markup</h2></a>
+<p>In general, libstdc++-v3 files should be formatted according to the GNU
+   C++ Coding Standard rules found in the file
+   <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE";>C++STYLE</a>.
+   Before any doxygen-specific formatting tweaks are made, please try to make
+   sure that the initial formatting is sound.
+</p>
+
+<p>Adding Doxygen markup to a file (informally called "doxygenating") is very
+   simple.  The Doxygen manual can be found
+   <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman";>here</a>.
+   We try to use a very-recent version of Doxygen.
+</p>
+
+<h3>Doxygen style guide</h3>
+<p>[incomplete and constantly evolving]</p>
+
+<p>For classes, use deque/vector/list and std::pair as examples.  For
+   functions, see their memeber functions, and the free functions in
+   <code>stl_algobase.h</code>.  Member functions of other container-like
+   types should read similarly to these member functions.
+</p>
+
+<p>These points accompany the first list in section 3.1 of the Doxygen manual:
+</p>
+<ol>
+ <li>Use the Javadoc style...</li>
+ <li>...not the Qt style.  The intermediate *'s are preferred.</li>
+ <li>Use the triple-slash style only for one-line comments (the "brief" mode).
+     Very recent versions of Doxygen permit full-mode comments in triple-slash
+     blocks, but the formatting still comes out wonky.</li>
+ <li>This is disgusting.  Don't do this.</li>
+</ol>
+
+<p>Use the @-style of commands, not the !-style.  Please be careful about
+   whitespace in your markup comments.  Most of the time it doesn't matter;
+   doxygen absorbs most whitespace, and both HTML and *roff are agnostic about
+   whitespace.  However, in &lt;pre&gt; blocks and @code/@endcode sections,
+   spacing can have "interesting" effects.
+</p>
+
+<p>Use either kind of grouping, as appropriate.  <code>doxygroups.cc</code>
+   exists for this purpose.  See <code>stl_iterator.h</code> for a good
+   example of the "other" kind of grouping.
+</p>
+
+<p>Please use markup tags like @p and @a when referring to things such as the
+   names of function parameters.  Use @e for emphasis when necessary.  Use @c
+   to refer to other standard names.  (Examples of all these abound in the
+   present code.)
+</p>
+
+</body>
+</html>
Index: docs/doxygen/mainpage.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/mainpage.html,v
retrieving revision 1.7
diff -u -3 -p -r1.7 mainpage.html
--- docs/doxygen/mainpage.html	24 Jun 2003 20:56:40 -0000	1.7
+++ docs/doxygen/mainpage.html	16 Jul 2003 23:58:49 -0000
@@ -42,47 +42,6 @@
    additional notes and additional classes/functions/etc.
 </p>
 
-<p>Here are quick links to the pages which we seem to use the most; a full
-   index is at the bottom:
-   <!-- Keep this in sync with below. -->
-   <ul>
-    <li><a href="annotated.html">Compound List</a>
-    <li><a href="classes.html">Alphabetical List</a>
-    <li><a href="namespaces.html">Namespace List</a>
-    <li><a href="files.html">File List</a>
-    <li><a href="modules.html">Modules</a>
-   </ul>
-</p>
-
-<h2> Generating this file </h2>
-<p>These HTML pages are automatically generated, along with the man pages.
-   The Makefile rules <code> 'make doxygen' </code> and
-   <code> 'make doxygen-maint' </code> in the libstdc++-v3 build directory
-   generates these pages using a tool called, appropriately enough, Doxygen.
-   To learn more about Doxygen, take a look at
-   <a href="http://www.doxygen.org/";>
-   <!-- snagged from the generated page -->
-   <img src="doxygen.png" alt="the Doxygen homepage"
-        align=center border=0 width=110 height=53>
-   </a>
-</p>
-
-<p>The libstdc++-v3 configuration files needed to generate doxygen output
-   are located:
-   <ul><li><code>docs/doxygen/user.cfg.in</code>
-       <li><code>docs/doxygen/run_doxygen</code>
-   </ul>
-</p>
-
-<h2> libstdc++-v3 doxygen style guide </h2>
-<p>In general, libstdc++-v3 files should be formatted according to the
-   GNU C++ Coding Standard rules found in the file <a
-href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE";>C++STYLE</a>.
-   Before any doxygen-specific formatting tweaks are made, please try to
-   make sure that the initial formatting is sound.
-</p>
-
-<h2> Full page index </h2>
 <p>Here are entry points to all the pages generated by Doxygen:
    <ul>
     <li><a href="index.html">Main Page</a>
@@ -99,14 +58,18 @@ href="http://gcc.gnu.org/onlinedocs/libs
    </ul>
 </p>
 
+<h2>Generating the documentation</h2>
+<p>These HTML pages are automatically generated, along with the man pages.
+   See <code>docs/doxygen/guide.html</code> in the source tree for how to
+   create (and write) the pages.
 
-<h2> License, Copyright, and Other Lawyerly Verbosity </h2>
+<h2>License, Copyright, and Other Lawyerly Verbosity</h2>
 <p>The libstdc++-v3 documentation is released under
    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/license.html";>
    these terms</a>.
 </p>
-<p>Part of the generated documentation involved comments
-   and notes from SGI, who says we gotta say this:
+<p>Part of the generated documentation involved comments and notes from
+   SGI, who says we gotta say this:
    <blockquote>
    Permission to use, copy, modify, distribute and sell this software and its
    documentation for any purpose is hereby granted without fee, provided
@@ -126,4 +89,3 @@ href="http://gcc.gnu.org/onlinedocs/libs
 
 </body>
 </html>
-


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]