diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 7bc4aaf9f59..f13fc2fb834 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,8 @@ +2003-07-16 Phil Edwards + + * docs/doxygen/mainpage.html: Move building/writing instructions... + * docs/doxygen/guide.html: ...to here. New file. + 2003-07-16 Jonathan Wakely * docs/html/ext/howto.html: Update URL for SGI STL docs. diff --git a/libstdc++-v3/docs/doxygen/guide.html b/libstdc++-v3/docs/doxygen/guide.html new file mode 100644 index 00000000000..7974358a8dc --- /dev/null +++ b/libstdc++-v3/docs/doxygen/guide.html @@ -0,0 +1,107 @@ + + + + + Build and Writing Guide for libstdc++-v3 Doxygen + + + + + +

libstdc++-v3 Source Documentation

+ +

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). +

+ + + +
+ +

Creating the pages

 +

The Makefile rules 'make doxygen', + 'make doxygen-maint', and 'make doxygen-man' + 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 + + + Doxygen + , a working version of g++ somewhere in the PATH, and + the GNU coreutils. + (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.) +

+ +

Careful observers will see that the Makefile rules simply call a script + from the source tree, run_doxygen, 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 '--help'.) +

+ +

If you wish to tweak the Doxygen settings, do so by editing + docs/doxygen/user.cfg.in. Notes to v3-hackers are written in + triple-# comments. +

+ +

Writing the markup

 +

In general, libstdc++-v3 files should be formatted according to the GNU + C++ Coding Standard rules found in the file + C++STYLE. + Before any doxygen-specific formatting tweaks are made, please try to make + sure that the initial formatting is sound. +

+ +

Adding Doxygen markup to a file (informally called "doxygenating") is very + simple. The Doxygen manual can be found + here. + We try to use a very-recent version of Doxygen. +

+ +

Doxygen style guide

+

[incomplete and constantly evolving]

+ +

For classes, use deque/vector/list and std::pair as examples. For + functions, see their memeber functions, and the free functions in + stl_algobase.h. Member functions of other container-like + types should read similarly to these member functions. +

+ +

These points accompany the first list in section 3.1 of the Doxygen manual: +

+
    +
  1. Use the Javadoc style...
    2. +
  2. ...not the Qt style. The intermediate *'s are preferred.
    3. +
  3. 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.
    4. +
  4. This is disgusting. Don't do this.
    5. +
+ +

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 <pre> blocks and @code/@endcode sections, + spacing can have "interesting" effects. +

+ +

Use either kind of grouping, as appropriate. doxygroups.cc + exists for this purpose. See stl_iterator.h for a good + example of the "other" kind of grouping. +

+ +

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.) +

+ + + diff --git a/libstdc++-v3/docs/doxygen/mainpage.html b/libstdc++-v3/docs/doxygen/mainpage.html index e0998fc0320..fdd40edcbe3 100644 --- a/libstdc++-v3/docs/doxygen/mainpage.html +++ b/libstdc++-v3/docs/doxygen/mainpage.html @@ -42,47 +42,6 @@ additional notes and additional classes/functions/etc.

-

Here are quick links to the pages which we seem to use the most; a full - index is at the bottom: - -

-

- -

Generating this file

-

These HTML pages are automatically generated, along with the man pages. - The Makefile rules 'make doxygen' and - 'make doxygen-maint' 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 - - - the Doxygen homepage - -

- -

The libstdc++-v3 configuration files needed to generate doxygen output - are located: -

-

- -

libstdc++-v3 doxygen style guide

-

In general, libstdc++-v3 files should be formatted according to the - GNU C++ Coding Standard rules found in the file C++STYLE. - Before any doxygen-specific formatting tweaks are made, please try to - make sure that the initial formatting is sound. -

- -

Full page index

Here are entry points to all the pages generated by Doxygen:

+

Generating the documentation

+

These HTML pages are automatically generated, along with the man pages. + See docs/doxygen/guide.html in the source tree for how to + create (and write) the pages. -

License, Copyright, and Other Lawyerly Verbosity

+

License, Copyright, and Other Lawyerly Verbosity

The libstdc++-v3 documentation is released under these terms.

-

Part of the generated documentation involved comments - and notes from SGI, who says we gotta say this: +

Part of the generated documentation involved comments and notes from + SGI, who says we gotta say this:

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/libstdc++/17_intro/C++STYLE">C++STYLE. -