Re: Discussion: Formalizing the deprecation process in GDB

[Joel Brobecker <brobecker@gnat.com>]

(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).

-- 
Joel