Re: Discussion: Formalizing the deprecation process in GDB

["Eli Zaretskii" <eliz at gnu dot org>]

> Date: Thu, 07 Oct 2004 11:37:45 -0400
> From: Andrew Cagney <cagney@gnu.org>
> Cc: gdb@sources.redhat.com
> 
> A system that is being continuously re-factored is not well suited for 
> detailed internals documentation - the effort is wasted.

Can we say that the features that are not going to change any time
soon are sufficiently documented?  For example, the CLI is not going
to be refactored any time soon (AFAIK), and yet its documentation
includes only 3 functions out of at least 10 it exports.  The
completion features (I mean their GDB-specific aspects, not the
general Readline mechanism) are not documented at all.

Another example is DWARF-2 support, whose ``documentation'' is 2
rather unhelpful sentences.

Core files are completely undocumented.

Etc., etc.  So I submit that our internal documentation's coverage is
very poor even in those non-contradictory parts where refactoring is
not a problem at all.

As for the refactoring factor (pun intended): I don't agree with the
``wasted effort'' argument.  Some areas are refactored very slowly, so
clearly things are quasy-stable enough to have them documented even to
the detailed level.  And in those areas which are in transition, we
can always decide to stop at the sufficiently high level to avoid
wasting the effort.  So this is IMHO not an excuse for failing to
document even the areas where development and change are facts of
life.

> Instead the high level architecture and medium level object models
> that are important.

Do we have these?

> There is no "migration" path.  The correct approach is:
> - delete all deprecated code
> - build
> - run testsuite
> - add a missing architecture vector method
> - repeat
> Instead of migrating, trying to reproduce each refactoring step, you 
> should leap frog.

As Dave explained, this paradigm is inappropriate for at least the
case of someone who is trying to introduce a new feature, not refactor
an old one.  In that case, there's no guidance a developer can find to
what code she should be using instaed of the deprecated one.