From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23044 invoked by alias); 9 Oct 2004 11:14:12 -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 23020 invoked from network); 9 Oct 2004 11:14:09 -0000 Received: from unknown (HELO balder.inter.net.il) (192.114.186.15) by sourceware.org with SMTP; 9 Oct 2004 11:14:09 -0000 Received: from zaretski (pns03-196-71.inter.net.il [80.230.196.71]) by balder.inter.net.il (Mirapoint Messaging Server MOS 3.3.7-GR) with ESMTP id DUV69338 (AUTH halo1); Sat, 9 Oct 2004 13:13:52 +0200 (IST) Date: Sun, 10 Oct 2004 21:31:00 -0000 From: "Eli Zaretskii" To: Andrew Cagney Message-ID: <01c4adf0$Blat.v2.2.2$b8d77220@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: <4166E0D3.8030607@gnu.org> (message from Andrew Cagney on Fri, 08 Oct 2004 14:47:47 -0400) Subject: Re: Discussion: Formalizing the deprecation process in GDB Reply-to: Eli Zaretskii References: <416562C9.90801@gnu.org> <01c4ad22$Blat.v2.2.2$73afa240@zahav.net.il> <4166E0D3.8030607@gnu.org> X-SW-Source: 2004-10/txt/msg00272.txt.bz2 > Date: Fri, 08 Oct 2004 14:47:47 -0400 > From: Andrew Cagney > Cc: dk@artimi.com, brobecker@gnat.com, gdb@sources.redhat.com > > The way the current CLI code works is i18n busted. I recently > deprecated several key CLI functions just to stop people adding code > using them. Of the functions that are not marked deprecated, do we envision that their APIs (as opposed to their inner workings) will undergo significant changes? If not, there's nothing to prevent us from documenting the API. > While there are new "draft" interfaces available they are > just draft, the corresponding internals (and perhaps the interfaces) > face significant change. When is that change planned, approximately, and did someone start working on its design? If the change is not close, or if we don't even know yet how to make the CLI i18n compatible, it could be years before the real change will happen, and we again can document the internals now. > Even the frame code isn't safe, which left the old design in the dust, > is now its self reaching its limits. It's looking at a refactoring that > will fundmentally change both it and the symtab. From frame has-a > unwinder; to frame has-a function (is a symbol) has-a unwinder. > > etc, etc, etc, Are you saying that I chose bad examples or are you saying that there's nothing in the GDB internals that can be documented because everything is under development? If the former, can we please go back to talking about the original issue: should we prefer Texinfo documentation to the code comments or the other way around? If you do mean the latter, then perhaps I should think seriously whether I want to be responsible for documentation of a project whose head maintainer thinks that internal documentation is more or less a waste of time. Btw, the ``under construction, subject to change without notice'' argument flies in the face of the code comments preference as well: if the code is so temporary, it isn't worth commenting.