From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9845 invoked by alias); 8 Oct 2004 10:38:18 -0000 Mailing-List: contact gdb-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sources.redhat.com Received: (qmail 9753 invoked from network); 8 Oct 2004 10:38:13 -0000 Received: from unknown (HELO balder.inter.net.il) (192.114.186.15) by sourceware.org with SMTP; 8 Oct 2004 10:38:13 -0000 Received: from zaretski (pns03-208-187.inter.net.il [80.230.208.187]) by balder.inter.net.il (Mirapoint Messaging Server MOS 3.3.7-GR) with ESMTP id DUV40489 (AUTH halo1); Fri, 8 Oct 2004 12:37:14 +0200 (IST) Date: Fri, 08 Oct 2004 11:45:00 -0000 From: "Eli Zaretskii" To: Andrew Cagney Message-ID: <01c4ad22$Blat.v2.2.2$73afa240@zahav.net.il> Content-Transfer-Encoding: 7BIT Content-Type: text/plain; charset=ISO-8859-1 CC: dk@artimi.com, brobecker@gnat.com, gdb@sources.redhat.com In-reply-to: <416562C9.90801@gnu.org> (message from Andrew Cagney on Thu, 07 Oct 2004 11:37:45 -0400) Subject: Re: Discussion: Formalizing the deprecation process in GDB Reply-to: Eli Zaretskii References: <416562C9.90801@gnu.org> X-SW-Source: 2004-10/txt/msg00248.txt.bz2 > Date: Thu, 07 Oct 2004 11:37:45 -0400 > From: Andrew Cagney > 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.