Re: FYI: minsyms documentation

[Yao Qi <yao at codesourcery dot com>]

On 12/23/2011 05:17 AM, Stan Shebs wrote:
> If everybody is able to madly hack away at the code without ever
> consulting the internals manual, then what purpose is it serving
> exactly?  Are newbies learning by reading the manual, or reading the

newbies are learning by manual reading at the beginning, even they can
get more accurate information from comments in code later.

> code?  If the latter, then gdbint.texinfo content might get more
> attention if it was redistributed into 1-2 page blocks at the tops of
> relevant source files.

This sounds good to me, but IMO, we still need gdbint.texinfo to
describe the overall view of components of gdb and their relationships,
which can not be put in source files.

In JDK, all the documentation to a class and its methods are written in
source file, and only one small text file is for package description.
In package description, the overview is given and relationship of these
classes is described.  Most of the doc in details are still in comment
of source file.  I don't think we can copy this approach here, but we
can do something similar here.  Put detailed doc in gdbint.texinfo to
relevant source files, and only leave overview and high-level doc in it.
 In this way, we don't have to pay much effort to keep gdbint.texinfo
synchronized with source, and gdbint.texinfo is still quite useful.

-- 
Yao (éå)