From: pme
Date: Thu, 27 Sep 2001 22:44:24 +0000 (+0000)
Subject: 2001-09-27 Phil Edwards
X-Git-Tag: upstream/4.9.2~91897
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=78ee80ac8cd369c4772387a374b5f3ce7302c9a5;p=platform%2Fupstream%2Flinaro-gcc.git
2001-09-27 Phil Edwards
* include/std/*: Add Doxygen hooks.
* docs/doxygen/Intro.3: New file, general intro to the man pages.
* docs/doxygen/mainpage.doxy: Formatting tweaks. List our own links
rather than using a generated index.
* docs/doxygen/user.cfg.in: Disable the index, enable man pages.
* docs/doxygen/run_doxygen: Massage the generated man pages, using...
* docs/doxygen/stdheader.cc: ...this new file.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@45850 138bc75d-0d04-0410-961f-82ee72b054a4
---
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 5fc8051..5c4de1b 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,13 @@
+2001-09-27 Phil Edwards
+
+ * include/std/*: Add Doxygen hooks.
+ * docs/doxygen/Intro.3: New file, general intro to the man pages.
+ * docs/doxygen/mainpage.doxy: Formatting tweaks. List our own links
+ rather than using a generated index.
+ * docs/doxygen/user.cfg.in: Disable the index, enable man pages.
+ * docs/doxygen/run_doxygen: Massage the generated man pages, using...
+ * docs/doxygen/stdheader.cc: ...this new file.
+
2001-09-26 Stan Shebs
* include/Makefile.am: Remove RCS Id strings.
diff --git a/libstdc++-v3/docs/doxygen/Intro.3 b/libstdc++-v3/docs/doxygen/Intro.3
new file mode 100644
index 0000000..5df718b
--- /dev/null
+++ b/libstdc++-v3/docs/doxygen/Intro.3
@@ -0,0 +1,24 @@
+.\" This man page is released under the FDL as part of libstdc++-v3.
+.TH Intro 3 "27 September 2001" "GNU libstdc++-v3" "Standard C++ Library"
+.SH NAME
+Intro \- Introduction to the GNU libstdc++-v3 man pages
+.SH DESCRIPTION
+
+This should mention the man pages generated for modules.
+
+.SH FILES
+
+Lots. Wish I knew enough *roff syntax to list them nicely.
+
+.SH CONFORMING TO
+Almost conforming to
+.BI "International Standard ISO/IEC 14882:1998(E), " "Programming Languages --- C++"
+(aka the C++ standard), in addition to corrections proposed by the Library
+Working Group,
+.SM JTC1/SC22/WG21.
+.SH SEE ALSO
+.UR
+http://gcc.gnu.org/libstdc++/
+.UE
+for the Frequently Asked Questions, online documentation, and more.
+
diff --git a/libstdc++-v3/docs/doxygen/mainpage.doxy b/libstdc++-v3/docs/doxygen/mainpage.doxy
index a05692b..f1fa54d 100644
--- a/libstdc++-v3/docs/doxygen/mainpage.doxy
+++ b/libstdc++-v3/docs/doxygen/mainpage.doxy
@@ -1,62 +1,75 @@
/*! \mainpage
- documentation overview
+ Documentation Overview
-
-There are two types of documentation for libstdc++-v3. One is the distribution documentation, which can be read
-here.
+
There are two types of documentation for libstdc++-v3. One is the
+ distribution documentation, which can be read online at
+ http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html
+ or offline from docs/html/documentation.html in the library source
+ directory.
-
-The other is the source documentation, of which this is the first page.
+
The other type is the source documentation, of which this is the first page.
+ Here are quick links to the pages which we seem to use the most; a full
+ index is at the bottom:
+
+
- generating this file
-
-This page is automatically generated. The Makefile rule make
-doxygen 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 webpage .
+
Generating this file
+This page is automatically generated. The Makefile rule make
+ doxygen
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
+ webpage.
-
-The libstdc++-v3 configuration files needed to generate doxygen output
-are located:
-
docs/doxygen/user.cfg.in
- docs/doxygen/maint.cfg.in
+The libstdc++-v3 configuration files needed to generate doxygen output
+ are located:
+
docs/doxygen/user.cfg.in
+ docs/doxygen/maint.cfg.in
+
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 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.
+ Before any doxygen-specific formatting tweaks are made, please try to
+ make sure that the initial formatting is sound.
-
-The formatting guidelines for using libstdc++-v3 with doxygen are
-still incomplete. There seems to be a marginal preference for the use
-of Java-Doc style formatting, with the idea that the single-line style
-(triple-slash) is the least intrusive mechanism for getting
-libstdc++-v3 documented and cross-referenced while at the same time
-minimizing disruption to the current formatting.
+
The formatting guidelines for using libstdc++-v3 with doxygen are still
+ incomplete. There seems to be a marginal preference for the use of
+ Java-Doc style formatting, with the idea that the single-line style
+ (triple-slash) is the least intrusive mechanism for getting libstdc++-v3
+ documented and cross-referenced while at the same time minimizing
+ disruption to the current formatting. Full documentation of functions
+ (parameter types, return values, etc) will require the slash-splat-splat
+ "extended C" commenting style.
-
-For the time being, please see include/bits/char_traits.h
-which is the test bed for a finished doxygen style guide.
+
Full page index
+Here are entry points to all the pages generated by Doxygen:
+
*/
-
-
-
-
-
-
-
diff --git a/libstdc++-v3/docs/doxygen/run_doxygen b/libstdc++-v3/docs/doxygen/run_doxygen
index 6bd83f0..d515dfd 100644
--- a/libstdc++-v3/docs/doxygen/run_doxygen
+++ b/libstdc++-v3/docs/doxygen/run_doxygen
@@ -1,6 +1,6 @@
#!/bin/sh
-# Runs doxygen. Possibly will massage the output files.
+# Runs doxygen and massages the output files.
#
# Synopsis: run_doxygen --mode=[user|maint] v3srcdir v3builddir
#
@@ -69,14 +69,6 @@ parse_options() {
mode=$arg ;;
--mode | --help | -h)
print_usage ;;
- --version | -v)
- # Aw, that's so cuuuute... don't ask, I needed it.
- blank=
- Id=is
- echo You expect this dinky script to track a version? Okay, here
- echo it $Id: run_doxygen,v 1.6 2001/07/11 19:35:47 pme Exp $blank
- exit 0
- ;;
*)
# this turned out to be a mess, maybe change to --srcdir=, etc
if test $srcdir = unset; then
@@ -129,12 +121,56 @@ chmod u+w $outdir
echo :: Finished, exit code was $?
)
-# mess with output files here?
+# Mess with the man pages. We don't need documentation of the internal
+# headers, since the man pages for those contain nothing useful anyhow. The
+# man pages for doxygen modules need to be renamed (or deleted). And the
+# generated #include lines need to be changed from the internal names to the
+# standard ones (e.g., "#include " -> "#include ").
+#
+# File names with embedded spaces (EVIL!) need to be....? renamed or removed?
+cd $outdir/man/man3 && {
+echo :: Fixing up the man pages...
+
+# requires GNU tools
+find . -name "* *" -print0 | xargs -0 rm
+rm *.h.3
+
+# can leave SGIextensions.3 alone, it's an okay name
+mv s20_3_1_base.3 Intro_functors.3
+mv s20_3_2_arithmetic.3 Arithmetic_functors.3
+mv s20_3_3_comparisons.3 Comparison_functors.3
+mv s20_3_4_logical.3 Logical_functors.3
+mv s20_3_5_negators.3 Negation_functors.3
+mv s20_3_6_binder.3 Binder_functors.3
+mv s20_3_7_adaptors.3 Func_ptr_functors.3
+mv s20_3_8_memadaptors.3 Member_ptr_functors.3
+
+# Standardize the displayed header names. If anyone who knows perl cares
+# enough to rewrite all this, feel free. This only gets run once a century,
+# and I'm off getting coffee then anyhow, so I didn't care enough to make
+# this super-fast.
+g++ ${srcdir}/docs/doxygen/stdheader.cc -o ./stdheader
+problematic=`egrep -l '#include <.*_.*>' [a-z]*.3`
+for f in $problematic; do
+ # this is also slow, but safe and easy to debug
+ oldh=`sed -n '/#include .*/\1/p' $f`
+ newh=`echo $oldh | ./stdheader`
+ sed "s=${oldh}=${newh}=" $f > TEMP
+ mv TEMP $f
+done
+rm stdheader
+
+cp ${srcdir}/docs/doxygen/Intro.3 .
+}
+
+# all done
echo ::
echo :: Doxygen output begins with
echo :: ${outdir}/html_${mode}/index.html
echo ::
+echo :: Man pages in ${outdir}/man
+echo ::
exit 0
diff --git a/libstdc++-v3/docs/doxygen/stdheader.cc b/libstdc++-v3/docs/doxygen/stdheader.cc
new file mode 100644
index 0000000..d705d01
--- /dev/null
+++ b/libstdc++-v3/docs/doxygen/stdheader.cc
@@ -0,0 +1,146 @@
+// This is a slow larval-stage kludge to help massage the generated man
+// pages. It's used like this:
+const char* const usage =
+"\nTakes on stdin, whitespace-separated words of the form\n"
+"\n"
+" [bits/]stl_foo.h\n"
+" [bits/]std_foo.h\n"
+"\n"
+"and writes on stdout the nearest matching standard header name.\n"
+"\n"
+"Takes no command-line arguments.\n"
+"\n";
+
+#include
+#include