1*404b540aSrobert<!DOCTYPE html 2*404b540aSrobert PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 3*404b540aSrobert "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 4*404b540aSrobert<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 5*404b540aSrobert<head> 6*404b540aSrobert <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> 7*404b540aSrobert <title>Build and Writing Guide for libstdc++ Doxygen</title> 8*404b540aSrobert <link href="style.css" rel="stylesheet" type="text/css"> 9*404b540aSrobert</head> 10*404b540aSrobert 11*404b540aSrobert<body bgcolor="#ffffff"> 12*404b540aSrobert 13*404b540aSrobert<h1>libstdc++ Source Documentation</h1> 14*404b540aSrobert 15*404b540aSrobert<p>This file is docs/doxygen/guide.html in the libstdc++ source tree. It 16*404b540aSrobert is not included in the generated pages (no real point to doing that). 17*404b540aSrobert</p> 18*404b540aSrobert 19*404b540aSrobert<ul> 20*404b540aSrobert <li><a href="#creating">Creating the pages</a></li> 21*404b540aSrobert <li><a href="#writing">Writing the markup</a></li> 22*404b540aSrobert</ul> 23*404b540aSrobert 24*404b540aSrobert<hr /> 25*404b540aSrobert 26*404b540aSrobert<a name="creating"><h2>Creating the pages</h2></a> 27*404b540aSrobert<p>The Makefile rules <code>'make doxygen'</code>, 28*404b540aSrobert <code>'make doxygen-maint'</code>, and <code>'make doxygen-man'</code> 29*404b540aSrobert in the libstdc++ build directory generate the user-level HTML docs, the 30*404b540aSrobert maintainer-level HTML docs, and the man pages, respectively. Prerequisite 31*404b540aSrobert tools are Bash 2.x, 32*404b540aSrobert <a href="http://www.doxygen.org/"> 33*404b540aSrobert <!-- snagged from the generated page --> 34*404b540aSrobert <img src="doxygen.png" alt="Doxygen" align=center border=0 width=110 height=53> 35*404b540aSrobert </a>, a working version of <code>g++</code> somewhere in the PATH, and 36*404b540aSrobert the <a href="http://www.gnu.org/software/coreutils/">GNU coreutils</a>. 37*404b540aSrobert 38*404b540aSrobert In addition, to generate the pretty pictures, the 39*404b540aSrobert <a href= 40*404b540aSrobert "http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</a> 41*404b540aSrobert package will need to be installed. 42*404b540aSrobert (g++ is used to build a program which manipulates man pages. GNU versions 43*404b540aSrobert of find, xargs, and possibly sed and grep are used, just because the GNU 44*404b540aSrobert versions make things very easy.) 45*404b540aSrobert</p> 46*404b540aSrobert 47*404b540aSrobert<p>Careful observers will see that the Makefile rules simply call a script 48*404b540aSrobert from the source tree, <code>run_doxygen</code>, which does the actual work 49*404b540aSrobert of running Doxygen and then (most importantly) massaging the output files. 50*404b540aSrobert If for some reason you prefer to not go through the Makefile, you can call 51*404b540aSrobert this script directly. (Start by passing <code>'--help'</code>.) 52*404b540aSrobert</p> 53*404b540aSrobert 54*404b540aSrobert<p>If you wish to tweak the Doxygen settings, do so by editing 55*404b540aSrobert <code>docs/doxygen/user.cfg.in</code>. Notes to v3-hackers are written in 56*404b540aSrobert triple-# comments. 57*404b540aSrobert</p> 58*404b540aSrobert 59*404b540aSrobert<a name="writing"><h2>Writing the markup</h2></a> 60*404b540aSrobert<p>In general, libstdc++ files should be formatted according to the GNU 61*404b540aSrobert C++ Coding Standard rules found in the file 62*404b540aSrobert <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>. 63*404b540aSrobert Before any doxygen-specific formatting tweaks are made, please try to make 64*404b540aSrobert sure that the initial formatting is sound. 65*404b540aSrobert</p> 66*404b540aSrobert 67*404b540aSrobert<p>Adding Doxygen markup to a file (informally called "doxygenating") is very 68*404b540aSrobert simple. The Doxygen manual can be found 69*404b540aSrobert <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</a>. 70*404b540aSrobert We try to use a very-recent version of Doxygen. 71*404b540aSrobert</p> 72*404b540aSrobert 73*404b540aSrobert<h3>Doxygen style guide</h3> 74*404b540aSrobert<p>[incomplete and constantly evolving]</p> 75*404b540aSrobert 76*404b540aSrobert<p>For classes, use deque/vector/list and std::pair as examples. For 77*404b540aSrobert functions, see their member functions, and the free functions in 78*404b540aSrobert <code>stl_algobase.h</code>. Member functions of other container-like 79*404b540aSrobert types should read similarly to these member functions. 80*404b540aSrobert</p> 81*404b540aSrobert 82*404b540aSrobert<p>These points accompany the first list in section 3.1 of the Doxygen manual: 83*404b540aSrobert</p> 84*404b540aSrobert<ol> 85*404b540aSrobert <li>Use the Javadoc style...</li> 86*404b540aSrobert <li>...not the Qt style. The intermediate *'s are preferred.</li> 87*404b540aSrobert <li>Use the triple-slash style only for one-line comments (the "brief" mode). 88*404b540aSrobert Very recent versions of Doxygen permit full-mode comments in triple-slash 89*404b540aSrobert blocks, but the formatting still comes out wonky.</li> 90*404b540aSrobert <li>This is disgusting. Don't do this.</li> 91*404b540aSrobert</ol> 92*404b540aSrobert 93*404b540aSrobert<p>Use the @-style of commands, not the !-style. Please be careful about 94*404b540aSrobert whitespace in your markup comments. Most of the time it doesn't matter; 95*404b540aSrobert doxygen absorbs most whitespace, and both HTML and *roff are agnostic about 96*404b540aSrobert whitespace. However, in <pre> blocks and @code/@endcode sections, 97*404b540aSrobert spacing can have "interesting" effects. 98*404b540aSrobert</p> 99*404b540aSrobert 100*404b540aSrobert<p>Use either kind of grouping, as appropriate. <code>doxygroups.cc</code> 101*404b540aSrobert exists for this purpose. See <code>stl_iterator.h</code> for a good 102*404b540aSrobert example of the "other" kind of grouping. 103*404b540aSrobert</p> 104*404b540aSrobert 105*404b540aSrobert<p>Please use markup tags like @p and @a when referring to things such as the 106*404b540aSrobert names of function parameters. Use @e for emphasis when necessary. Use @c 107*404b540aSrobert to refer to other standard names. (Examples of all these abound in the 108*404b540aSrobert present code.) 109*404b540aSrobert</p> 110*404b540aSrobert 111*404b540aSrobert</body> 112*404b540aSrobert</html> 113
