Add Doxygen support to GDB

gdb/doc/ChangeLog

@@ -1,3 +1,17 @@
+2014-02-10  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.
+
 2014-02-10  Doug Evans  <xdje42@gmail.com>
 
 	* Makefile.in (GDB_DOC_FILES): Add guile.texi.

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

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

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
+

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

gdb/doc/Makefile.in

@@ -185,6 +185,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

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>

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

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;
+}