[v3] initial Doxygen doc-generation support added

[Phil Edwards <pedwards at disaster dot jaj dot com>]

There are a lot of good ideas and suggestions that have been bouncing
around the v3 list regarding doxygen; I figured if I actually updated that
placeholder script with something useful, more people could chime in.

This adds two rules to the v3 makefile, "doxygen" and "doxygen-maint",
neither of which is ever run by default.  The script does a lot of paranoid
sanity-checking and then runs doxygen to produce HTML docs for either
"users" or "maintainers".  Other formats (man pages, LaTeX, whatever)
are in the doxygen config files but turned off.

Neither mode produces any useful documentation because none of the hooks
are in the include/source files.  Yet.  Those of you who have a hankerin'
to write some good clear technical documentation, have at it.  We need to
make a delineation between user info and maintainer info, and I'd like to
add some markers to completely elide some of the implementation details
from the docs in any mode, but that's for later.

The doxygen config files are somewhat large, and not included here.

Comments and corrections appreciated.  I expect most of this will be
tweaked around from this state before it becomes useful.



2001-03-24  Phil Edwards  <pme@sources.redhat.com>

	* Makefile.am:  New targets, doxygen and doxygen-maint.
	* Makefile.in:  Regenerated.
	* docs/doxygen/run_doxygen:  Finally implemented.
	* docs/doxygen/maint.cfg.in:  New file.
	* docs/doxygen/user.cfg.in:  New file.


Index: Makefile.am
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/Makefile.am,v
retrieving revision 1.17
diff -u -3 -p -r1.17 Makefile.am
--- Makefile.am	2001/02/03 09:01:40	1.17
+++ Makefile.am	2001/03/25 02:18:09
@@ -44,6 +44,20 @@ check-install: $(top_builddir)/mkcheck
 	  cd testsuite; \
 	  $${builddir}/mkcheck 1 $${builddir} $${srcdir} $(prefix))
 
+# These two rules seem messy.
+doxygen:
+	-(srcdir=`cd ${top_srcdir}; pwd`; \
+	  outdir=`pwd`; \
+	  ${srcdir}/docs/doxygen/run_doxygen --mode=user $${srcdir} $${outdir})
+
+doxygen-maint:
+	-(srcdir=`cd ${top_srcdir}; pwd`; \
+	  outdir=`pwd`; \
+	  ${srcdir}/docs/doxygen/run_doxygen --mode=maint $${srcdir} $${outdir})
+
+.PHONY: doxygen doxygen-maint
+
+
 # Multilib support.
 MAKEOVERRIDES=
 
Index: docs/doxygen/run_doxygen
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/run_doxygen,v
retrieving revision 1.1
diff -u -3 -p -r1.1 run_doxygen
--- run_doxygen	2000/12/10 04:03:08	1.1
+++ run_doxygen	2001/03/25 02:18:10
@@ -1,6 +1,110 @@
 #!/bin/sh
 
+# Runs doxygen.  Possibly will massage the output files.
+#
+# Synopsis:  run_doxygen --mode=[user|maint]  v3srcdir  v3builddir
+#
+# Originally hacked together by Phil Edwards <pme@sources.redhat.com>
+# $Id$
 
-# This file is a placeholder to keep the doxygen subdir in place.  It
-# will be used to test for the presence of doxygen(1) and run it.
+
+# We could check that the version of doxygen is >= this variable, but that's
+# just a pain.  Punt for now and rely on the maintainer to read this.  :-)
+DOXYVER=1.2.6
+
+print_usage() {
+    cat 1>&2 <<EOF
+Usage:  run_doxygen --mode=MODE [<options>] <src-dir> <output-dir>
+      MODE is one of:
+          maint          Generate maintainers' documentation (lots more;
+                             exposes non-public members, etc).
+          user           Generate user-level library documentation.
+
+      more options when i think of them
+
+Note:  Requires Doxygen ${DOXYVER} or later; get it at
+       ftp://ftp.stack.nl/pub/users/dimitri/doxygen-${DOXYVER}.src.tar.gz
+
+EOF
+    exit 1
+}
+
+parse_options() {
+  for o
+  do
+    # Blatantly ripped from autoconf, er, I mean, "gratefully standing
+    # on the shoulders of those giants who have gone before us."
+    case "$o" in
+      -*=*) arg=`echo "$o" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
+      *) arg= ;;
+    esac
+
+    case "$o" in
+      --mode=*)
+        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$blank
+        exit 0
+        ;;
+      *)
+        # this turned out to be a mess, maybe change to --srcdir=, etc
+        if test $srcdir = unset; then
+          srcdir=$o
+        elif test $outdir = unset; then
+          outdir=${o}/docs/doxygen
+        else
+          echo run_doxygen error:  Too many arguments 1>&2
+          exit 1
+        fi
+        ;;
+      esac
+  done
+}
+
+
+# script begins here
+mode=unset
+srcdir=unset
+outdir=unset
+
+parse_options $*
+
+if test $srcdir = unset || test $outdir = unset || test $mode = unset; then
+    # this could be better
+    echo run_doxygen error:  You have not given enough information...! 1>&2
+    print_usage
+fi
+
+case x"$mode" in
+    xuser | xmaint)  ;;  # ochen khorosho
+    *)
+      echo run_doxygen error:  $mode is an invalid mode 1>&2
+      exit 1 ;;
+esac
+
+# test for doxygen version here?
+
+test -d $outdir || (mkdir -p $outdir ; chmod u+w $outdir)
+(
+  set -e
+  cd $srcdir
+  sed -e "s=@outdir@=${outdir}=" docs/doxygen/${mode}.cfg.in \
+      > ${outdir}/${mode}.cfg
+  doxygen ${outdir}/${mode}.cfg
+)
+
+# mess with output files here?
+
+echo ::
+echo :: Doxygen output begins with
+echo :: ${outdir}/html_${mode}/index.html
+echo ::
+
+exit 0
 
cvs server: docs/doxygen/maint.cfg.in is a new entry, no comparison available
cvs server: docs/doxygen/user.cfg.in is a new entry, no comparison available