[PATCH] Use Doxygen for internals documentation

[Stan Shebs <stanshebs@earthlink.net>]

[-- Attachment #1: Type: text/plain, Size: 1257 bytes --]

Here is the official patch for the introduction of Doxygen that I
proposed last fall.

This differs from the RFC version in including a filter as
suggested by Pedro, and having an index page that points to the
different sets of pages.

Among other things, the filter gives us the option of flagging
Doxygen comments with "/* * ", which is lower-impact than the
previous requirement of putting "/**" on a line by itself - in
other words, just adding a " *" to existing comments.

As before, "cd doc; make doxy" in an objdir creates, then browse
doc/doxy/index.html to connect to everything.

In the absence of any fatal flaws, I expect to commit this next
week, and then follow up with patches that doxygenate some
representative header files.  At some point we'll also want to
add a snapshot-generated set of pages to the website.

Stan
stan@codesourcery.com

2014-02-06  Stan Shebs  <stan@codesourcery.com>

	Add Doxygen support.
	* Makefile.in (doxy): New action, generates Doxygen files.
	(DOXYGEN): New.
	(doxyedit): New.
	* Doxyfile-base.in: New file.
	* Doxyfile-gdb-api.in: New file.
	* Doxyfile-gdb-xref.in: New file.
	* Doxyfile-gdbserver.in: New file.
	* doxy-index.in: New file.
	* filter-for-doxygen: New file.
	* filter-params.pl: New file.




[-- Attachment #2: doxy-patch-3 --]
[-- Type: text/plain, Size: 12501 bytes --]

diff --git a/gdb/doc/Doxyfile-base.in b/gdb/doc/Doxyfile-base.in
new file mode 100644
index 0000000..1a6bcab
--- /dev/null
+++ b/gdb/doc/Doxyfile-base.in
@@ -0,0 +1,92 @@
+# Copyright (C) 2014 Free Software Foundation, Inc.
+
+# Base doxyfile for GDB.
+# This file is part of GDB.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# The definitions in this file are shared by several different
+# renditions of GDB documentation, and should reflect common
+# GDB practices and assumptions.
+
+# (Note that we are not following a common doxygen practice, which is
+# to include the entirety of doxygen's large default Doxyfile, and
+# edit it slightly for the project.  Instead, these Doxyfile fragments
+# include only parameter settings that differ from the default.)
+
+PROJECT_NAME = "GDB"
+
+# Start out with an everything-is-documented assumption.  (Later
+# on we may want to limit to only specific areas.)
+
+EXTRACT_ALL = YES
+
+# These are intended for GDB developers, so include anything flagged
+# "internal".
+
+INTERNAL_DOCS = YES
+
+# Always dig through subdirectories.
+
+RECURSIVE = YES
+
+INCLUDE_PATH = @srcdir@/../ @srcdir@/../common @srcdir@/../../include/
+
+# Exclude testsuite and other subdirectories that do not have any code
+# that goes into GDB or GDBserver.
+
+EXCLUDE = @srcdir@/../gdbserver/ \
+                   ../gdbserver/ \
+          @srcdir@/../gnulib/ \
+		   ../build-gnulib/ \
+          @srcdir@/../testsuite/ \
+		   ../testsuite/ \
+          @srcdir@/../stubs/
+
+# Scrub out any stuff that might be a problem for Doxygen.
+
+INPUT_FILTER =  @srcdir@/filter-for-doxygen
+
+# Comment this out (or set to YES) to see lots of finicky complaints.
+
+WARN_IF_DOC_ERROR = NO
+
+# By default, HTML will be generated.
+
+# We are missing javascript to make this work?
+#HTML_DYNAMIC_SECTIONS = YES
+
+# In 1.8 only?
+#HTML_INDEX_NUM_ENTRIES = 10
+
+# We never have a use for a LaTex version of this.
+
+GENERATE_LATEX = NO
+
+# We always want to get to sources easily.
+
+SOURCE_BROWSER = YES
+
+FORCE_LOCAL_INCLUDES = YES
+
+# We would like to have full macro expansion, but it's very slow.
+
+ENABLE_PREPROCESSING = YES
+#MACRO_EXPANSION = YES
+#EXPAND_ONLY_PREDEF = YES
+#PREDEFINED = __attribute__(x)= __extension__=
+
+# Suppress the huge volume of chatter.
+
+QUIET = YES
diff --git a/gdb/doc/Doxyfile-gdb-api.in b/gdb/doc/Doxyfile-gdb-api.in
new file mode 100644
index 0000000..02f8bdd
--- /dev/null
+++ b/gdb/doc/Doxyfile-gdb-api.in
@@ -0,0 +1,38 @@
+# Copyright (C) 2014 Free Software Foundation, Inc.
+
+# Doxygen file for GDB internal API.
+# This file is part of GDB.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+@INCLUDE = Doxyfile-base
+
+PROJECT_NAME = "GDB (API)"
+
+# Enumerate the files to process.  In general these should be header
+# files with definitions of general interest, rather than ones that
+# are specific to a single target or configuration.  (The cross
+# reference pages are available to developers wanting a list of
+# everything.)
+
+INPUT = @srcdir@/../defs.h \
+        @srcdir@/../minsyms.h \
+        @srcdir@/../utils.h
+
+HTML_OUTPUT = ./doxy/gdb-api
+
+# Suppress classes/structs local to source files, they are unlikely
+# to be of general API interest.
+
+EXTRACT_LOCAL_CLASSES = NO
diff --git a/gdb/doc/Doxyfile-gdb-xref.in b/gdb/doc/Doxyfile-gdb-xref.in
new file mode 100644
index 0000000..bca9c3c
--- /dev/null
+++ b/gdb/doc/Doxyfile-gdb-xref.in
@@ -0,0 +1,44 @@
+# Copyright (C) 2014 Free Software Foundation, Inc.
+
+# Doxygen file for a full GDB cross-reference.
+# This file is part of GDB.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+@INCLUDE = Doxyfile-base
+
+PROJECT_NAME = "GDB (xrefs)"
+
+# Get all the sources.
+
+INPUT = @srcdir@/../ ../
+
+HTML_OUTPUT = ./doxy/gdb-xref
+
+# We want to use the XML for analysis and statistics.
+
+GENERATE_XML = YES
+XML_OUTPUT = ./doxy/xml
+
+# Include everything possible.
+
+EXTRACT_PRIVATE = YES
+EXTRACT_STATIC = YES
+
+# Build a full cross-reference.
+
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION = YES
+REFERENCES_LINK_SOURCE = NO
+
diff --git a/gdb/doc/Doxyfile-gdbserver.in b/gdb/doc/Doxyfile-gdbserver.in
new file mode 100644
index 0000000..cf73908
--- /dev/null
+++ b/gdb/doc/Doxyfile-gdbserver.in
@@ -0,0 +1,45 @@
+# Copyright (C) 2014 Free Software Foundation, Inc.
+
+# Doxygen file for a GDBserver cross-reference.
+# This file is part of GDB.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+@INCLUDE = Doxyfile-base
+
+PROJECT_NAME = "GDBserver"
+
+# Override the general include path.
+
+INCLUDE_PATH = @srcdir@/../common @srcdir@/../../include/
+
+# Include just the directories that go into GDBserver.
+
+INPUT = @srcdir@/../gdbserver @srcdir@/../common @srcdir@/../nat
+
+# Override the generic exclude list.
+# gdbreplay is its own program, avoid duplicate symbols.
+
+EXCLUDE = @srcdir@/../gdbserver/gdbreplay.c
+
+HTML_OUTPUT = ./doxy/gdbserver
+
+# Build a full cross-reference.
+
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION = YES
+REFERENCES_LINK_SOURCE = NO
+
+EXTRACT_PRIVATE = YES
+EXTRACT_STATIC = YES
diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index cf63e4a..39c160d 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -184,6 +184,43 @@ ps: gdb.ps stabs.ps refcard.ps annotate.ps
 html: $(HTMLFILES)
 pdf: $(PDFFILES)
 man: $(MANS)
+
+DOXYGEN = doxygen
+doxyedit = sed -e 's,@srcdir\@,$(srcdir),g'
+
+doxy:	doxy/index.html \
+	doxy/gdb-api/index.html \
+	doxy/gdb-xref/index.html \
+	doxy/gdbserver/index.html
+
+doxy/index.html: $(srcdir)/doxy-index.in
+	-mkdir -p doxy
+	cp $(srcdir)/doxy-index.in doxy/index.html
+
+doxy/gdb-api/index.html: Doxyfile-gdb-api Doxyfile-base
+	-mkdir -p doxy
+	$(DOXYGEN) Doxyfile-gdb-api
+
+doxy/gdb-xref/index.html: Doxyfile-gdb-xref Doxyfile-base
+	-mkdir -p doxy
+	$(DOXYGEN) Doxyfile-gdb-xref
+
+doxy/gdbserver/index.html: Doxyfile-gdbserver Doxyfile-base
+	-mkdir -p doxy
+	$(DOXYGEN) Doxyfile-gdbserver
+
+Doxyfile-base:	$(srcdir)/Doxyfile-base.in 
+	$(doxyedit) $(srcdir)/Doxyfile-base.in >Doxyfile-base
+
+Doxyfile-gdb-api:	$(srcdir)/Doxyfile-gdb-api.in 
+	$(doxyedit) $(srcdir)/Doxyfile-gdb-api.in >Doxyfile-gdb-api
+
+Doxyfile-gdb-xref:	$(srcdir)/Doxyfile-gdb-xref.in
+	$(doxyedit) $(srcdir)/Doxyfile-gdb-xref.in >Doxyfile-gdb-xref
+
+Doxyfile-gdbserver:	$(srcdir)/Doxyfile-gdbserver.in
+	$(doxyedit) $(srcdir)/Doxyfile-gdbserver.in >Doxyfile-gdbserver
+
 all-doc: info dvi ps # pdf
 diststuff: info man
 	rm -f gdb-cfg.texi GDBvn.texi
diff --git a/gdb/doc/doxy-index.in b/gdb/doc/doxy-index.in
new file mode 100644
index 0000000..b869038
--- /dev/null
+++ b/gdb/doc/doxy-index.in
@@ -0,0 +1,76 @@
+<!-- Copyright (C) 2014 Free Software Foundation, Inc.
+
+Navigation page for Doxygen-generated GDB info.
+
+This file is part of GDB.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<html lang="en">
+<head>
+<title>GDB Internals (Doxygen)</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="GDB Internals (Doxygen)">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css">
+</style>
+</head>
+<body>
+
+<p>
+This page is the index to doxygen-generated pages describing GDB
+internals.
+
+<p>
+These are primarily useful for people working on GDB itself.  Users of
+GDB, people working with stubs, and people working on frontends to GDB
+are all better served by the GDB manual, which is the official
+definition for all of GDB's external interfaces.
+
+<h2>
+<a href="gdb-api/index.html">GDB internal API</a>
+</h2>
+
+<p>
+The GDB internal API consists of all definitions and functions
+that are of interest to multiple areas of the debugger.
+
+<p>
+Note that this internal API reference lists only header files for
+which doxygen-type documentation has been added, and explicitly listed
+as a part of the API.
+
+<h2>
+<a href="gdb-xref/index.html">GDB full source cross-reference</a>
+</h2>
+
+<p>
+This cross-reference includes all of the GDB sources proper, omitting
+support libraries such as BFD, and files that are not compiled into
+GDB.
+
+<p>
+It is not guaranteed to report all uses of a construct, and you should
+independently check non-use of a symbol before trying to remove it.
+
+<h2>
+<a href="gdbserver/index.html">GDBserver source cross-reference</a>
+</h2>
+
+<p>
+Similar to the GDB cross-reference, but for GDBserver sources.
+
+</body>
+</html>
diff --git a/gdb/doc/filter-for-doxygen b/gdb/doc/filter-for-doxygen
new file mode 100755
index 0000000..457d088
--- /dev/null
+++ b/gdb/doc/filter-for-doxygen
@@ -0,0 +1,14 @@
+#!/bin/sh
+
+# This filters GDB source before Doxygen can get confused by it;
+# this script is listed in the doxyfile. The output is not very
+# pretty, but at least we get output that Doxygen can understand.
+#
+# $1 is a source file of some kind. The source we wish doxygen to
+# process is put on stdout.
+
+# (Adapted from gcc/contrib/filter_gcc_for_doxygen)
+
+dir=`dirname $0`
+perl $dir/filter-params.pl < $1
+exit 0
diff --git a/gdb/doc/filter-params.pl b/gdb/doc/filter-params.pl
new file mode 100644
index 0000000..eedcc5b
--- /dev/null
+++ b/gdb/doc/filter-params.pl
@@ -0,0 +1,11 @@
+#!/usr/bin/perl
+
+# This Perl script tweaks GDB sources to be more useful for Doxygen.
+
+while (<>) {
+    # Allow "/* * " as an equivalent to "/** ", better for Emacs compat.
+    s/^\/\* \* /\/** /sg;
+    # Manually expand macro seen in structs and such.
+    s/ENUM_BITFIELD[ \t]*\((.*?)\)/__extension__ enum $1/sg;
+    print;
+}