Re: Autogenerate gdbarch doc for internals manual

Jeremy Bennett
2008-08-01T18:34:49Z

On Fri, 2008-08-01 at 10:06 -0700, Stan Shebs wrote:
> Undeterred by the stunning lack of response to my last internals manuals
> query (http://sourceware.org/ml/gdb/2008-07/msg00309.html, not too late
> to speak up :-) ), I bring up an idea suggested on irc, which is to
> generate the internals manual's detailed description of gdbarch methods
> from gdbarch.sh . Although I'm not generally a fan of autogenerated docs
> - I find they tend to be heavy on syntax, and light on semantics - the
> internals manual has fallen way behind what is actually in gdbarch, and
> there are other manual sections that can talk more about how all the
> different methods work together.
>
> Mechanically, the way I see it working is that running gdbarch.sh
> produces a third file, doc/gdbarch.texi, which is then included in
> doc/gdbint.texinfo. Some gdbint.texinfo bits will migrate into
> gdbarch.sh; I don't think there will be a problem including texinfo
> markup in gdbarch.sh, just need basic @foo{} constructs to get passed
> through. This is going to be more of a background task for me, but I
> wanted to get some agreement on the direction before starting to tinker.
>
> Stan

Hi Stan,

As an outsider, who's recently dived into the workings of GDB, I'd
encourage anything that keeps the internals manual up to date and
complete. I'm a strong believer in auto-generating as much of this sort
of documentation as possible. Write it down once in one place is the
only way that ever works. Even in the current internals manual, a lot of
the content duplicates comments in the header files - except it's out of
date.

Auto-generating does tend to emphasize the syntax, but even that's
better than nothing. A good discipline in commenting global functions
and variables goes a long way to fixing this. GDB code is well
disciplined already, so this should fit with the coding culture.

For what it's worth I've had good experience with Doxygen as a tool for
this, so long as the commenting discipling is observed. That's for the C
code - you would have to pre-process for gdbarch.sh.

I'd be dismayed if the GFDL/GPL conflict was to get in the way of this.
Every internals manual I know quotes heavily from the code it is
describing - doing the same automatically doesn't particularly change
the legal position. I'd suggest that what is needed is not a particular
exception for GDB, but a general clarification of the position for all
GPL/LGPL/AGPL/GFDL projects.

The most significant problem I found was lack of a "big picture" section
to the internals document. What are the chunks I put together to port a
new architecture to GDB? I'm writing up my recent experiences in doing a
first port of an architecture to GDB. When it's complete I'll share it
with this group.

Keep up the good work.

Jeremy

--
Tel: +44 (1202) 416955
Cell: +44 (7970) 676050
SkypeID: jeremybennett
Email: jeremy.bennett@embecosm.com
Web: www.embecosm.com