RE: Discussion: Formalizing the deprecation process in GDB

["Dave Korn" <dk at artimi dot com>]

> -----Original Message-----
> From: Andrew Cagney 
> Sent: 07 October 2004 16:49
> To: Joel Brobecker; Dave Korn; 'Eli Zaretskii'

> >>>> > I do agree with Andrew that the place were developers search
> >>>> > for documentation is the code. 
> >>
> >>> 
> >>>   Not me!  I look for the internals docs!  And complain 
> bitterly when I
> >>> can't find them (because they don't exist) or they're 
> years out of date!

  It's just occurred to me that this could be read as a specific complaint
or accusation against gdb's documentation, rather than a comment on the
generally sorry state of documentation as a whole in the software industry.
No such inference was implied nor intended; sorry if anyone thought I was
criticising gdb with that statement!

> > Well, one of the contributing factors of docs guetting out of date
> > is that they are out of the developer's view. 

  Things like the doxygen format are good for that: you keep the doco for
(eg) a function right inline with the code, so it stands a good chance of
being kept up-to-date whenever anyone works on that bit of code, but then
there's an automated process that gathers all the documentation from its
many-and-widely-scattered locations in the source, and compiles it into one
nice neat help file.  I mention it because I think it's a good idea, but
have to say that I can't see any way it could be reasonably retrofitted to a
project on the scale of gdb, so I'm not sure if it was even worth mentioning
except out of academic interest....

> "gdbarch.sh", "target.h", "inferior.h", ... are all better examples. 
> For those, my things to do one day include get them into a format 
> similar to observer.texi so that at least the interface is 
> single source.

...  although maybe it could be useful in limited areas of application such
as this one!

  Thing is, coming newly to gdb, there isn't even anything to tell you to
look in any of those files.  It can be quite disheartening when you read

"This section is pretty much obsolete. The functionality described here has
largely been replaced by pseudo-registers and the mechanisms described in
Chapter 9 [Using Different Register and Memory Data Representations], page
30."

and you go to the reference and see

"The way GDB manipulates registers is undergoing significant change.
Many of the macros and functions refered to in this section are likely to be
subject to further revision."

and then you're left wondering "Well, what revision?  Which macros and
functions?  What should I actually _do_ about this?".  Or when you see lots
of things to do with registers have been deprecated, and there's this new
high-level mechanism called regcache, which is some kind of cache of the
inferiors registers, but there's no overview of the new scheme anywhere - or
at any rate, not in regcache.[ch].  Part of my problem is undoubtedly just
unfamiliarity with the code, so take my opinions on this matter as relating
particularly to the situation for someone getting to grips with gdb's
sources for the first time: it's very hard to break into.
 
> I think separate documentation is good for recording 
> processes such as 
> releasing gdb or version numbers; and higher level architecture and 
> perhaps even some medium level models (showing how it is ment 
> to be not 
> how bu----ed it currently is :-).

  Heh, basically this is indeed what I'm wishing for.

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....