Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney <cagney@gnu.org>]

> (this discussion about the internals documentation is for the purpose
> of formalizing the deprecation mechanism)
> 
> 
>>>> > 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!
> 
> 
> Well, one of the contributing factors of docs guetting out of date
> is that they are out of the developer's view. You can thank Eli for
> his tremendous job at keeping the gdbint doc in great shape, but also
> alerting us when some documentation needs to be added/modified in that
> manual.
> 
> But in any case, my point was not that we should get rid of the
> internals manual entirely. There are parts that are more useful
> in this manual rather than the in the code. Parts that explain
> the big pictures, for instance, how everything fits together, etc.
> 
> However, sections such as the section that explain what observers
> are, which ones are implemented, and what they should be used for,
> in my opinion, should be documented in the code. (actually, now that
> I think of it, the observer code is now generated from the doc -
> but I'm sure I can find other examples).

Yea, bad example :-)

"observer.texi" illustrates a [contraversial?] compromise, at least the 
documentation is in a single place.  (BTW, JeffJ pointed out to me that 
the observer.texi doco has a bug - it doesn't document how to add a new 
observer - knowing to modify observer.texi isn't "obvious" :-).

"gdbarch.sh", "target.h", "inferior.h", ... are all better examples. 
For those, my things to do one day include get them into a format 
similar to observer.texi so that at least the interface is single source.

I think separate documentation is good for recording processes such as 
releasing gdb or version numbers; and higher level architecture and 
perhaps even some medium level models (showing how it is ment to be not 
how bu----ed it currently is :-).

Andrew