RE: Discussion: Formalizing the deprecation process in GDB

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

> -----Original Message-----
> From: gdb-owner On Behalf Of Joel Brobecker
> Sent: 07 October 2004 03:41

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

> This does not mean that I am suggesting that we get rid of gdbint
> entirely. I see chapters and sections that can only be placed in
> a separate documentation, such as how to add support for a new
> host for instance. But the documentation about partial symbol
> tables, for instance, would be much more useful directly in
> symtab.h or symtab.c.

  Ok, I also read the code, but I very much appreciate having good
documentation in book format.  If you've got a serious chunk of architecture
to learn about, it's a lot easier if it's all in one file that you can print
out and browse through at your leisure rather than a page here and a page
there scattered across many files.

  FWIW I reckon gcc is getting it very right these days.  There's a
heavyweight internals manual that explains the architecture and big picture
issues.  Each file that implements a substantial module of functionality
then also has documentation about its internals and implementation at the
top of the file.  Usually you only need the internals manual, and only if
you find yourself rummaging around in the depths of alias analysis or
something chasing a bug do you find yourself needing the per-file-internal
documentation.

> I don't know about others, but I have read the gdbint manual once
> from cover to cover almost 4 years ago, and never refered to it
> anymore.

  Since opinions are being invited, I'll just mention that I'm currently
working on an internal version of gdb for which I'm having to up-port a
5.x-compatible backend to 6.x series.  I sometimes find it *ever* so hard
when faced with yet another deprecated__ this or obsoleted_ that to know
what the new and approved replacement is, and it often takes a combination
of the internals manual, the in-source documentation and comments, and much
searching of the list archive for the actual patch that made the deprecation
to see how it was done at the time and understand the background and
reasoning to it.  I understand the reasons for using this technique and
agree that it's sound engineering practice and necessary for the onward
development of gdb, but I would like an easier solution to the general
problem of knowing what to replace something with, and one that could be
used off-line or on those occasions when sourceware goes down and you can't
get at the list archive!


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