This is the mail archive of the gdb@sources.redhat.com mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Discussion: Formalizing the deprecation process in GDB


(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



Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]