Re: Discussion: Formalizing the deprecation process in GDB

["Eli Zaretskii" <eliz@gnu.org>]

> Date: Fri, 08 Oct 2004 14:47:47 -0400
> From: Andrew Cagney <cagney@gnu.org>
> 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.