From: Stan Shebs Date: Mon, 10 Feb 2014 23:01:14 +0000 (+1030) Subject: Add Doxygen support to GDB X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=1e0a51780bc504ff110cc623954cdf9e71a26ad1;p=binutils-gdb.git Add Doxygen support to GDB --- diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 1dd7231a443..52fede47251 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,17 @@ +2014-02-10 Stan Shebs + + 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 * Makefile.in (GDB_DOC_FILES): Add guile.texi. diff --git a/gdb/doc/Doxyfile-base.in b/gdb/doc/Doxyfile-base.in new file mode 100644 index 00000000000..1a6bcab6e6f --- /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 . + +# 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 00000000000..02f8bddba8d --- /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 . + +@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 00000000000..bca9c3c1f46 --- /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 . + +@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 00000000000..cf739084cad --- /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 . + +@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 a578d3ad73a..4375b20ff1f 100644 --- a/gdb/doc/Makefile.in +++ b/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 diff --git a/gdb/doc/doxy-index.in b/gdb/doc/doxy-index.in new file mode 100644 index 00000000000..b8690386940 --- /dev/null +++ b/gdb/doc/doxy-index.in @@ -0,0 +1,76 @@ + + + + +GDB Internals (Doxygen) + + + + + + + +

+This page is the index to doxygen-generated pages describing GDB +internals. + +

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

+GDB internal API +

+ +

+The GDB internal API consists of all definitions and functions +that are of interest to multiple areas of the debugger. + +

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

+GDB full source cross-reference +

+ +

+This cross-reference includes all of the GDB sources proper, omitting +support libraries such as BFD, and files that are not compiled into +GDB. + +

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

+GDBserver source cross-reference +

+ +

+Similar to the GDB cross-reference, but for GDBserver sources. + + + diff --git a/gdb/doc/filter-for-doxygen b/gdb/doc/filter-for-doxygen new file mode 100755 index 00000000000..457d088c104 --- /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 00000000000..b5d0f6b53ef --- /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; +}