[PATCH] Use Doxygen for internals documentation

[PATCH] Use Doxygen for internals documentation

[Stan Shebs]

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

Re: [PATCH] Use Doxygen for internals documentation

[Yao Qi]

Stan,
I applied this patch and run 'make doxy' in dir doc.  It looks good!

On 02/07/2014 07:55 AM, Stan Shebs wrote:
> +<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.

We may add a link to GDB manual.

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

Missing copyright header?

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

Likewise.

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

Why do we need this substitution here?  Anything wrong if we don't do
the substitution?  I don't recall this was asked in last review.

-- 
Yao (齐尧)

Re: [PATCH] Use Doxygen for internals documentation

[Ludovic Courtès]

Stan Shebs <stanshebs@earthlink.net> skribis:

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

What would happen to gdbint.info?

Thanks,
Ludo’.

Re: [PATCH] Use Doxygen for internals documentation

[Eli Zaretskii]

> From: ludo@gnu.org (Ludovic Courtès)
> Date: Fri, 07 Feb 2014 16:36:42 +0100
> 
> Stan Shebs <stanshebs@earthlink.net> skribis:
> 
> > Here is the official patch for the introduction of Doxygen that I
> > proposed last fall.
> 
> What would happen to gdbint.info?

It was deleted already, see the GDB 7.7 tarball.

Re: [PATCH] Use Doxygen for internals documentation

[Doug Evans]

On Thu, Feb 6, 2014 at 3:55 PM, Stan Shebs <stanshebs@earthlink.net> wrote:
> 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.

Awesome!

Re: [PATCH] Use Doxygen for internals documentation

[Sergio Durigan Junior]

On Friday, February 07 2014, Ludovic Courtès wrote:

> Stan Shebs <stanshebs@earthlink.net> skribis:
>
>> Here is the official patch for the introduction of Doxygen that I
>> proposed last fall.
>
> What would happen to gdbint.info?

Hey Ludo!

gdbint.info has been deprecated recently, and all its contents have been
moved to the wiki.

<http://sourceware.org/gdb/wiki/InternalsManual>

Cheers,

-- 
Sergio

Re: [PATCH] Use Doxygen for internals documentation

[Ludovic Courtès]

Hi Sergio,

Sergio Durigan Junior <sergiodj@redhat.com> skribis:

> On Friday, February 07 2014, Ludovic Courtès wrote:
>
>> Stan Shebs <stanshebs@earthlink.net> skribis:
>>
>>> Here is the official patch for the introduction of Doxygen that I
>>> proposed last fall.
>>
>> What would happen to gdbint.info?
>
> Hey Ludo!
>
> gdbint.info has been deprecated recently, and all its contents have been
> moved to the wiki.
>
> <http://sourceware.org/gdb/wiki/InternalsManual>

Thanks for the info.

That’s a move I consider regrettable, but hey.

Ludo’.

Re: [PATCH] Use Doxygen for internals documentation

[Stan Shebs]

On 2/6/14 3:55 PM, Stan Shebs wrote:
> Here is the official patch for the introduction of Doxygen that I
> proposed last fall.

This is now pushed.

I've added http://sourceware.org/gdb/wiki/DoxygenForGDB as the
initial info on what to do with it.

I've also got defs.h, minsyms.h, and utils.[hc] in various states
of doxygenation, but won't spend a whole lot more time on them
before pushing them.

For other popular header files, I suggest that if people
want to jump on any, that we use the wiki page as a simple
reservation system - although basic doxygenation of a file
need take only a few minutes, one invariably sees many ways
to fix up the comment blocks.

Have fun!

Stan
stan@codesourcery.com

Re: [PATCH] Use Doxygen for internals documentation

[Mark Kettenis]

> Date: Tue, 11 Feb 2014 11:07:53 -0800
> From: Stan Shebs <stanshebs@earthlink.net>
> 
> On 2/6/14 3:55 PM, Stan Shebs wrote:
> > Here is the official patch for the introduction of Doxygen that I
> > proposed last fall.
> 
> This is now pushed.
> 
> I've added http://sourceware.org/gdb/wiki/DoxygenForGDB as the
> initial info on what to do with it.
> 
> I've also got defs.h, minsyms.h, and utils.[hc] in various states
> of doxygenation, but won't spend a whole lot more time on them
> before pushing them.
> 
> For other popular header files, I suggest that if people
> want to jump on any, that we use the wiki page as a simple
> reservation system - although basic doxygenation of a file
> need take only a few minutes, one invariably sees many ways
> to fix up the comment blocks.

When did we agree that using doxygen was a good idea?

I don't want to spend my time on uglifying the source code with stuff
that will never result in usable documentation.

I don't want to be distracted by markup when I'm reading source code
or comments.

Most of all, I don't want to spend any time on arguing about these
stupid things.

Re: [PATCH] Use Doxygen for internals documentation

[Eli Zaretskii]

> Date: Tue, 11 Feb 2014 20:19:42 +0100 (CET)
> From: Mark Kettenis <mark.kettenis@xs4all.nl>
> CC: gdb-patches@sourceware.org
> 
> When did we agree that using doxygen was a good idea?

Some of us agreed in this discussion:

  https://sourceware.org/ml/gdb/2013-08/msg00015.html

Re: [PATCH] Use Doxygen for internals documentation

[Stan Shebs]

On 2/11/14 11:19 AM, Mark Kettenis wrote:
>> Date: Tue, 11 Feb 2014 11:07:53 -0800
>> From: Stan Shebs <stanshebs@earthlink.net>
>>
>> On 2/6/14 3:55 PM, Stan Shebs wrote:
>>> Here is the official patch for the introduction of Doxygen that I
>>> proposed last fall.
>>
>> This is now pushed.
>>
>> I've added http://sourceware.org/gdb/wiki/DoxygenForGDB as the
>> initial info on what to do with it.
>>
>> I've also got defs.h, minsyms.h, and utils.[hc] in various states
>> of doxygenation, but won't spend a whole lot more time on them
>> before pushing them.
>>
>> For other popular header files, I suggest that if people
>> want to jump on any, that we use the wiki page as a simple
>> reservation system - although basic doxygenation of a file
>> need take only a few minutes, one invariably sees many ways
>> to fix up the comment blocks.
> 
> When did we agree that using doxygen was a good idea?

We did discuss it last August as part of my original proposal, then
last October with the first version of this patch.  It wasn't 100%
support, but there was enough to be worth the experiment.

> I don't want to spend my time on uglifying the source code with stuff
> that will never result in usable documentation.
> 
> I don't want to be distracted by markup when I'm reading source code
> or comments.

Basically we're talking one additional asterisk per header declaration,
which doesn't seem that onerous.  Doxygen annotation *could* get more
elaborate, but if it does, it will be because people are getting enough
value out of it to want to spend time putting the additional effort in.

> Most of all, I don't want to spend any time on arguing about these
> stupid things.

""

:-)

Stan
stan@codesourcery.com