What's an annex? stratum?

What's an annex? stratum?

[Michael Eager]

Looking at target.c, I see some terms which are less
than clear:  annex and stratum.  Could someone tell me
what these mean?

There is a mention of "annex" in the GDB doc, but it's
not clear that this is the same as in target.c.  This
refers to an XML document and refers to
gdb/features/gdb-target.dtd which doesn't exist.  In
target.c, it appears that an annex is an address space
of some kind.

There is one mention of "strata" in the docs, under
maintenance commands.

Aside:  there are comments in the gdb code which tell me
that the previous code did things badly and that the new
scheme is better.  Usually there's no description of the
new scheme.  I don't know about others, but I find these
comments are both distracting and unhelpful.


-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Re: What's an annex? stratum?

[Stan Shebs]

Michael Eager wrote:
> Looking at target.c, I see some terms which are less
> than clear:  annex and stratum.  Could someone tell me
> what these mean?
"Annex" is apparently an introduction of Andrew's from 2004, does kind 
of look like an address space addition, although not clear that it's 
fully implemented.

"Stratum" is an old concept, merely a way to talk about different levels 
of the target stack. In practice, the stacking concept isn't as clean as 
it must have seemed initially; sometimes you really want to run a target 
op in a vector down in the stack, sometimes you want to replace a target 
vector in the middle. So we introduce strata as a way to find a 
mid-stack target vector of a desired type. First big block comment in 
target.h goes into a bit more detail.
>
> Aside:  there are comments in the gdb code which tell me
> that the previous code did things badly and that the new
> scheme is better.  Usually there's no description of the
> new scheme.  I don't know about others, but I find these
> comments are both distracting and unhelpful.
Probably not much consolation, but I'm having the same trouble with 
Mozilla sources these days. :-)

Stan

Re: What's an annex? stratum?

[Michael Eager]

Stan Shebs wrote:
> Michael Eager wrote:
>> Looking at target.c, I see some terms which are less
>> than clear:  annex and stratum.  Could someone tell me
>> what these mean?
> "Annex" is apparently an introduction of Andrew's from 2004, does kind 
> of look like an address space addition, although not clear that it's 
> fully implemented.

I'm assuming that the XML target description in the docs is similarly
incomplete and/or obsolete.

There seems to be a fair amount of cruft in the code, and
even more in the documentation.  Sigh.

> "Stratum" is an old concept, merely a way to talk about different levels 
> of the target stack. In practice, the stacking concept isn't as clean as 
> it must have seemed initially; sometimes you really want to run a target 
> op in a vector down in the stack, sometimes you want to replace a target 
> vector in the middle. So we introduce strata as a way to find a 
> mid-stack target vector of a desired type. First big block comment in 
> target.h goes into a bit more detail.

I read the comments, but it doesn't really say what the target stack is.
I see the enum for different strata, giving a hierarchy.

I can see that you might layer a core file on top of an executable
file, so that searching for a symbol/address was passed down until
you found the one which contained it.  But how does thread/process/
download fit into this picture?

-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Re: What's an annex? stratum?

[Eli Zaretskii]

> Date: Sat, 23 Jun 2007 12:08:40 -0700
> From: Michael Eager <eager@eagercon.com>
> CC:  gdb@sources.redhat.com
> 
> I'm assuming that the XML target description in the docs is similarly
> incomplete and/or obsolete.

On the contrary: it is relatively very new and its documentation is
supposed to be quite complete (at least as far as the manuals go; if
you are talking about the code, that's a different matter).  So if you
find some portions of its documentation unclear or incomplete, please
point that out.

> There seems to be a fair amount of cruft in the code, and
> even more in the documentation.  Sigh.

I'm sure we will welcome patches.

Re: What's an annex? stratum?

[Michael Eager]

Eli Zaretskii wrote:
>> Date: Sat, 23 Jun 2007 12:08:40 -0700
>> From: Michael Eager <eager@eagercon.com>
>> CC:  gdb@sources.redhat.com
>>
>> I'm assuming that the XML target description in the docs is similarly
>> incomplete and/or obsolete.
> 
> On the contrary: it is relatively very new and its documentation is
> supposed to be quite complete (at least as far as the manuals go; if
> you are talking about the code, that's a different matter).  So if you
> find some portions of its documentation unclear or incomplete, please
> point that out.

The doc refers to a non-existent DTD file which is supposed to
describe the XML target description annex.  I assumed it was obsolete.

It's not clear whether this is the same annex referenced in target.c.

>> There seems to be a fair amount of cruft in the code, and
>> even more in the documentation.  Sigh.
> 
> I'm sure we will welcome patches.

I'd be happy to.  It's not easy to create patches when it's
unclear whether the doc is out of date or the source hasn't
caught up yet.  There are many areas where the docs are out
sync with the source.

-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Re: What's an annex? stratum?

[Daniel Jacobowitz]

On Sat, Jun 23, 2007 at 01:51:50PM -0700, Michael Eager wrote:
> The doc refers to a non-existent DTD file which is supposed to
> describe the XML target description annex.  I assumed it was obsolete.

You are looking at mismatched source and manual, I assume - you didn't
say what versions you were using.  In the HEAD version and snapshots,
gdb/features/gdb-target.dtd does exist and the documentation describes
it.  The most accessible copy of the online docs refers to HEAD; I
wonder if we should make the manual for the last release more
prominent instead.

> It's not clear whether this is the same annex referenced in target.c.

Annexes are auxilliary data passed to target_xfer_partial:
    /* Request that OPS transfer up to LEN 8-bit bytes of the target's
       OBJECT.  The OFFSET, for a seekable object, specifies the
       starting point.  The ANNEX can be used to provide additional
       data-specific information to the target.

For the remote protocol, this usually means qXfer packets, like so:

`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
     Read uninterpreted bytes from the target's special data area
     identified by the keyword OBJECT.  Request LENGTH bytes starting
     at OFFSET bytes into the data.  The content and encoding of ANNEX
     is specific to the object; it can supply additional details about
     what data to access.

-- 
Daniel Jacobowitz
CodeSourcery

Re: What's an annex? stratum?

[Michael Eager]

Daniel Jacobowitz wrote:
> On Sat, Jun 23, 2007 at 01:51:50PM -0700, Michael Eager wrote:
>> The doc refers to a non-existent DTD file which is supposed to
>> describe the XML target description annex.  I assumed it was obsolete.
> 
> You are looking at mismatched source and manual, I assume - you didn't
> say what versions you were using.  In the HEAD version and snapshots,
> gdb/features/gdb-target.dtd does exist and the documentation describes
> it.  The most accessible copy of the online docs refers to HEAD; I
> wonder if we should make the manual for the last release more
> prominent instead.

I'm looking at the current CVS tree.  Perhaps my update failed.
I had some network problem earlier today.

>> It's not clear whether this is the same annex referenced in target.c.
> 
> Annexes are auxilliary data passed to target_xfer_partial:
>     /* Request that OPS transfer up to LEN 8-bit bytes of the target's
>        OBJECT.  The OFFSET, for a seekable object, specifies the
>        starting point.  The ANNEX can be used to provide additional
>        data-specific information to the target.
> 
> For the remote protocol, this usually means qXfer packets, like so:
> 
> `qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
>      Read uninterpreted bytes from the target's special data area
>      identified by the keyword OBJECT.  Request LENGTH bytes starting
>      at OFFSET bytes into the data.  The content and encoding of ANNEX
>      is specific to the object; it can supply additional details about
>      what data to access.

Thanks.


-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Re: What's an annex? stratum?

[Eli Zaretskii]

> Date: Sat, 23 Jun 2007 14:40:28 -0700
> From: Michael Eager <eager@eagercon.com>
> 
> Daniel Jacobowitz wrote:
> > On Sat, Jun 23, 2007 at 01:51:50PM -0700, Michael Eager wrote:
> >> The doc refers to a non-existent DTD file which is supposed to
> >> describe the XML target description annex.  I assumed it was obsolete.
> > 
> > You are looking at mismatched source and manual, I assume - you didn't
> > say what versions you were using.  In the HEAD version and snapshots,
> > gdb/features/gdb-target.dtd does exist and the documentation describes
> > it.  The most accessible copy of the online docs refers to HEAD; I
> > wonder if we should make the manual for the last release more
> > prominent instead.
> 
> I'm looking at the current CVS tree.

Well, in that case, you should have gdb-target.dtd.  I do have it in
my sandbox.

Re: What's an annex? stratum?

[Michael Eager]

Eli Zaretskii wrote:
>> Date: Sat, 23 Jun 2007 14:40:28 -0700
>> From: Michael Eager <eager@eagercon.com>
>>
>> Daniel Jacobowitz wrote:
>>> On Sat, Jun 23, 2007 at 01:51:50PM -0700, Michael Eager wrote:
>>>> The doc refers to a non-existent DTD file which is supposed to
>>>> describe the XML target description annex.  I assumed it was obsolete.
>>> You are looking at mismatched source and manual, I assume - you didn't
>>> say what versions you were using.  In the HEAD version and snapshots,
>>> gdb/features/gdb-target.dtd does exist and the documentation describes
>>> it.  The most accessible copy of the online docs refers to HEAD; I
>>> wonder if we should make the manual for the last release more
>>> prominent instead.
>> I'm looking at the current CVS tree.
> 
> Well, in that case, you should have gdb-target.dtd.  I do have it in
> my sandbox.

Yes, I have it.  My CVS update failed because of network issues.

-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Re: What's an annex? stratum?

[Jim Blandy]

Michael Eager <eager@eagercon.com> writes:
> Stan Shebs wrote:
>> Michael Eager wrote:
>>> Looking at target.c, I see some terms which are less
>>> than clear:  annex and stratum.  Could someone tell me
>>> what these mean?
>> "Annex" is apparently an introduction of Andrew's from 2004, does
>> kind of look like an address space addition, although not clear that
>> it's fully implemented.
>
> I'm assuming that the XML target description in the docs is similarly
> incomplete and/or obsolete.
>
> There seems to be a fair amount of cruft in the code, and
> even more in the documentation.  Sigh.

For what it's worth --- we don't invest enough time in
doc/gdbint.texinfo to keep it a clear, accurate reference to the
code.  (For me, at least, this is a deliberate decision.)  It's more a
collection of the clearer explanations that have appeared on the
mailing list over time.

gdb.texinfo, however, is supposed to be complete, accurate, and clear.

Re: What's an annex? stratum?

[Michael Eager]

Jim Blandy wrote:

> For what it's worth --- we don't invest enough time in
> doc/gdbint.texinfo to keep it a clear, accurate reference to the
> code.  (For me, at least, this is a deliberate decision.)  It's more a
> collection of the clearer explanations that have appeared on the
> mailing list over time.

Unfortunately, much of it is obsolete.  Some sections, like 9.6,
make this explicit.  Other sections say that the area is in flux,
like section 9.7.  Other sections don't tell you that they are
out of date (like the section about libgdb?).

Some important parts are simply missing, like the sections titled
Console Printing, TUI, Frame Interpretation, Inferior Call Setup, and
others.

I don't mean to harp on the documentation, but often the "clearer
explanations" amount to commentary about how the old technique didn't
work well and the new technique is better.  That may be true, but it
doesn't reveal much about how to use the technique.

If I get to the point where I think I really understand an area,
I'll be happy to contribute to documentation improvements.  I'm
not there at the moment.

-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Re: What's an annex? stratum?

[Jim Blandy]

Michael Eager <eager@eagercon.com> writes:
>> For what it's worth --- we don't invest enough time in
>> doc/gdbint.texinfo to keep it a clear, accurate reference to the
>> code.  (For me, at least, this is a deliberate decision.)  It's more a
>> collection of the clearer explanations that have appeared on the
>> mailing list over time.
>
> Unfortunately, much of it is obsolete.  Some sections, like 9.6,
> make this explicit.  Other sections say that the area is in flux,
> like section 9.7.  Other sections don't tell you that they are
> out of date (like the section about libgdb?).
>
> Some important parts are simply missing, like the sections titled
> Console Printing, TUI, Frame Interpretation, Inferior Call Setup, and
> others.
>
> I don't mean to harp on the documentation, but often the "clearer
> explanations" amount to commentary about how the old technique didn't
> work well and the new technique is better.  That may be true, but it
> doesn't reveal much about how to use the technique.
>
> If I get to the point where I think I really understand an area,
> I'll be happy to contribute to documentation improvements.  I'm
> not there at the moment.

Well, let me try again to say what I meant: if you're new to GDB, you
should not start by reading gdbint.texinfo.  Instead, start by reading
and grepping, and then experiment by debugging GDB with itself.  If
you ask a question, people may occasionally refer you to
gdbint.texinfo.  But it's not useful as a getting started guide for
GDB hackers, and I think the effort required to make it so is far more
than any of us have available.

I'm even a little skeptical about the value of internals documentation
at all.  It seems to me that explanations like that belong in the
code, where people are more likely to see them, keep them up to date,
and delete them when appropriate.

Re: What's an annex? stratum?

[Paul Koning]

>>>>> "Jim" == Jim Blandy <jimb@codesourcery.com> writes:

 Jim> Well, let me try again to say what I meant: if you're new to
 Jim> GDB, you should not start by reading gdbint.texinfo.  Instead,
 Jim> start by reading and grepping, and then experiment by debugging
 Jim> GDB with itself.  If you ask a question, people may occasionally
 Jim> refer you to gdbint.texinfo.  But it's not useful as a getting
 Jim> started guide for GDB hackers, and I think the effort required
 Jim> to make it so is far more than any of us have available.

 Jim> I'm even a little skeptical about the value of internals
 Jim> documentation at all.  It seems to me that explanations like
 Jim> that belong in the code, where people are more likely to see
 Jim> them, keep them up to date, and delete them when appropriate.

That's really unfortunate.  Comments in code are useful but they are
no substitute for properly written internals documentation.

By contrast, the internals documentation of GCC seems to be pretty
helpful and reasonably up to date.

Given a program as complex and inscrutable as GDB, if the best you can
tell newcomers is "use the source, Luke", you're going to turn off a
lot of them.  Only those who are extremely motivated will make
progress against such a barrier.

For example: Bug #186 has been troubling us on and off for a long
time.  I would like to fix it.  But given that this involves going off
into the deep jungle of the GDB symbol and type machinery, and the
fact that there is no useable documentation for this stuff, I haven't
been able to do this.

	 paul

Re: What's an annex? stratum?

[Daniel Jacobowitz]

On Mon, Jun 25, 2007 at 03:19:32PM -0400, Paul Koning wrote:
> That's really unfortunate.  Comments in code are useful but they are
> no substitute for properly written internals documentation.
> 
> By contrast, the internals documentation of GCC seems to be pretty
> helpful and reasonably up to date.

You may have noticed that GCC has approximately ten times as many
active contributors.  Maybe twenty.  It is not twenty times as
complex.  There is no feasible way for the GDB contributors to even
respond to all the incoming bug reports; maintaining internals
documentation of the quality of GCC's would probably require two
contributors' full time effort.

Do you see two spare contributors?  If you do, let me know, please.

> For example: Bug #186 has been troubling us on and off for a long
> time.  I would like to fix it.  But given that this involves going off
> into the deep jungle of the GDB symbol and type machinery, and the
> fact that there is no useable documentation for this stuff, I haven't
> been able to do this.

It's really not as inscrutable as you make it sound, and there are
plenty of people willing to answer questions.  Especially for people
who are interested in fixing bugs and/or improving the documentation.

-- 
Daniel Jacobowitz
CodeSourcery

Re: What's an annex? stratum?

[Robert Dewar]

On Mon, Jun 25, 2007 at 03:19:32PM -0400, Paul Koning wrote:
> That's really unfortunate.  Comments in code are useful but they are
> no substitute for properly written internals documentation.

I disagree, properly arranged comments in the code can most
certainly serve as internals documentation, and have a FAR
better chance of being kept up to date. I am opposed to having
separate internals documentation, I think it is much better to
have this in the source files.

Just so you know you cannot assume consensus on Paul's view here :-)

Re: What's an annex? stratum?

[Paul Koning]

>>>>> "Robert" == Robert Dewar <dewar@adacore.com> writes:

 Robert> On Mon, Jun 25, 2007 at 03:19:32PM -0400, Paul Koning wrote:
 >> That's really unfortunate.  Comments in code are useful but they
 >> are no substitute for properly written internals documentation.

 Robert> I disagree, properly arranged comments in the code can most
 Robert> certainly serve as internals documentation, and have a FAR
 Robert> better chance of being kept up to date. I am opposed to
 Robert> having separate internals documentation, I think it is much
 Robert> better to have this in the source files.

Usual practice is for source comments to be local explanation, not
global explanation.

But in any case, if internals documentation existed in the sources,
I'd be a happy camper.

    paul

Re: What's an annex? stratum?

[Michael Eager]

Paul Koning wrote:
>>>>>> "Robert" == Robert Dewar <dewar@adacore.com> writes:
> 
>  Robert> On Mon, Jun 25, 2007 at 03:19:32PM -0400, Paul Koning wrote:
>  >> That's really unfortunate.  Comments in code are useful but they
>  >> are no substitute for properly written internals documentation.
> 
>  Robert> I disagree, properly arranged comments in the code can most
>  Robert> certainly serve as internals documentation, and have a FAR
>  Robert> better chance of being kept up to date. I am opposed to
>  Robert> having separate internals documentation, I think it is much
>  Robert> better to have this in the source files.
> 
> Usual practice is for source comments to be local explanation, not
> global explanation.

Documentation provides context which is not often available in
source comments.  The source comments are valuable, but you have
to know where to start or the context in which the comments are
appropriate.  (For example, my questions about annex and stratum
are not answered in the source.)

Internals documentation provides a guide through the program in
some kind of logical order.  It's difficult to provide that order
at the file or function scope.

> But in any case, if internals documentation existed in the sources,
> I'd be a happy camper.

Me too.

-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Re: What's an annex? stratum?

[Robert Dewar]

Michael Eager wrote:


> Internals documentation provides a guide through the program in
> some kind of logical order.  It's difficult to provide that order
> at the file or function scope.

Well the sources can provide a clear logical order,
e.g. the child hierarchy and the separate specs and bodies in an
Ada program. Anyway, see the GNAT front end, where by policy there
are NO separate design documents, for an indication of what I
consider ideal, or almost ideal (probably one short page of the
form .. start here, then ... would be helpful).
> 
>> But in any case, if internals documentation existed in the sources,
>> I'd be a happy camper.
> 
> Me too.
> 

Re: What's an annex? stratum?

[Robert Dewar]

Robert Dewar wrote:
> Michael Eager wrote:
> 
> 
>> Internals documentation provides a guide through the program in
>> some kind of logical order.  It's difficult to provide that order
>> at the file or function scope.
> 
> Well the sources can provide a clear logical order,
> e.g. the child hierarchy and the separate specs and bodies in an
> Ada program. Anyway, see the GNAT front end, where by policy there
> are NO separate design documents, for an indication of what I
> consider ideal, or almost ideal (probably one short page of the
> form .. start here, then ... would be helpful).

For instance, I am not sure there is anywhere in the front end
that says that par-chx is the parser routines for chapter x
constructs in the RM, and sem_chx is the semantics routines.
One thing that helps in the case of Ada is that everyone is
familiar with the standard document (the Ada RM) so that provides
an overall organization if the sources follow it closely (which
they do for GNAT). Following the C standard closely would not
be so helpful, and of course there is no analogous standard for
the back end.

Re: What's an annex? stratum?

[Eli Zaretskii]

> Date: Mon, 25 Jun 2007 15:38:07 -0400
> From: Robert Dewar <dewar@adacore.com>
> 
> On Mon, Jun 25, 2007 at 03:19:32PM -0400, Paul Koning wrote:
> > That's really unfortunate.  Comments in code are useful but they are
> > no substitute for properly written internals documentation.
> 
> I disagree, properly arranged comments in the code can most
> certainly serve as internals documentation

Code comments lack good provisions for such important aspects of
documentation as cross-references, indices, and hierarchical
structure.  Without these, all comments can present is an unstructured
collection of unrelated notes.

> I am opposed to having separate internals documentation, I think it
> is much better to have this in the source files.

That's not surprising: programmers don't like writing documentation as
much as they like writing code.  That is one reason why gdbint.texinfo
is in such poor shape.

In any case, if people here believe comments are a reasonable
substitute for documentation, perhaps I should from now on reject code
patches that do not explain themselves clearly, and do not contain
enough references to other related portions of GDB.

Re: What's an annex? stratum?

[Robert Dewar]

Eli Zaretskii wrote:

> In any case, if people here believe comments are a reasonable
> substitute for documentation, perhaps I should from now on reject code
> patches that do not explain themselves clearly, and do not contain
> enough references to other related portions of GDB.

You should do that in *any* case, inadequately documented code
is never acceptable.

Re: What's an annex? stratum?

[Eli Zaretskii]

> Date: Mon, 25 Jun 2007 16:44:01 -0400
> From: Robert Dewar <dewar@adacore.com>
> CC:  pkoning@equallogic.com,  jimb@codesourcery.com,  eager@eagercon.com, 
>  stanshebs@earthlink.net,  gdb@sources.redhat.com
> 
> Eli Zaretskii wrote:
> 
> > In any case, if people here believe comments are a reasonable
> > substitute for documentation, perhaps I should from now on reject code
> > patches that do not explain themselves clearly, and do not contain
> > enough references to other related portions of GDB.
> 
> You should do that in *any* case, inadequately documented code
> is never acceptable.

You aren't familiar with my standards of ``adequate comments''.

Re: What's an annex? stratum?

[Robert Dewar]

Eli Zaretskii wrote:

> You aren't familiar with my standards of ``adequate comments''.

Well then you probably are not familiar with the GNAT front end :-)

To me, code that is lacking in full documentation is unacceptable
(yes, most code around meets that criterion).

Re: What's an annex? stratum?

[Robert Dewar]

Robert Dewar wrote:
> Eli Zaretskii wrote:
> 
>> You aren't familiar with my standards of ``adequate comments''.
> 
> Well then you probably are not familiar with the GNAT front end :-)
> 
> To me, code that is lacking in full documentation is unacceptable
> (yes, most code around meets that criterion).

Just to be clearer, I mean most code around is indeed lacking in
full documentation. In particular, things that are often missing
are

global documentation (yes, this can be in separate documents if
they are kept up to date).

local documentation that does NOT depend on guessing what variable
names mean, or reading what code does.

In particular documentation about what you did NOT do and why not
(that's something you definitely cannot deduce from the code, but
is often very important).

Re: What's an annex? stratum?

[Markus Deuling]

Eli Zaretskii wrote:

> That's not surprising: programmers don't like writing documentation as
> much as they like writing code.  That is one reason why gdbint.texinfo
> is in such poor shape.
> 
> In any case, if people here believe comments are a reasonable
> substitute for documentation, perhaps I should from now on reject code
> patches that do not explain themselves clearly, and do not contain
> enough references to other related portions of GDB.
> 

Maybe the process of getting a patch into mainline should be changed. Currently a patch without a proper
Changelog has no chance. Maybe we should extend that and say a patch must have Changelog and one or two
lines (or even moren) in documentation whenever reasonable.

For example the guy that wrote the part for inferior function calls definitely wrote no doc :-)

For my opinion GDB's Internal Manual is very important and should be cultivated much more.

-- 
Markus Deuling
GNU Toolchain for Linux on Cell BE
deuling@de.ibm.com

Re: What's an annex? stratum?

[Robert Dewar]

Markus Deuling wrote:
> Eli Zaretskii wrote:
> 
>> That's not surprising: programmers don't like writing documentation as
>> much as they like writing code.  That is one reason why gdbint.texinfo
>> is in such poor shape.
>>
>> In any case, if people here believe comments are a reasonable
>> substitute for documentation, perhaps I should from now on reject code
>> patches that do not explain themselves clearly, and do not contain
>> enough references to other related portions of GDB.
>>
> 
> Maybe the process of getting a patch into mainline should be changed. Currently a patch without a proper
> Changelog has no chance. Maybe we should extend that and say a patch must have Changelog and one or two
> lines (or even moren) in documentation whenever reasonable.

It's a very important principle that stuff in the changelog is *not* a 
substitute for proper documentation in the source. That's a common
mistake (I catch it all the time in the GNAT sources, where all
checkins get reviewed by me with this in mind :-))
> 
> For example the guy that wrote the part for inferior function calls definitely wrote no doc :-)
> 
> For my opinion GDB's Internal Manual is very important and should be cultivated much more.
> 

Re: What's an annex? stratum?

[Jim Blandy]

The question "is X worthwhile" is ill-formed.  We all understand that
the real question is, "given our time and abilities, is X among the
things we should do now?"

At the moment, GDB:

- can't print a C++ map<string, string> value in any reasonable form,
  or even a vector<int>, or carry out many other essential C++
  operations,

- can't debug multiple processes at the same time,

- is slow to start up on large programs, and uses a lot of memory,

- can't let other threads continue to run while one is stopped,

- can't be scripted in a reasonable language,

- or do many other things we all could think of.

Time spent on the internals documentation has, itself, no effect on
users' experience with GDB.  It's only worthwhile if that time, plus
the time then spent doing something users *will* notice, is less than
the time needed just to do something user-visible without internals
documentation.

I want to hear an internals documentation advocate say, "I'm going to
work on the internals documentation because I think the date at which
user-visible project X is complete will move closer when I do so."

I am *not* a seat-of-the-pants coder.  Read prologue-value.h or
macrotab.h if you want to know my values.  But I know that life is
short and uncertain, and that the pursuit of beauty has no regard for
that.

Re: What's an annex? stratum?

[Nick Roberts]

 > At the moment, GDB:
 > 
 > - can't print a C++ map<string, string> value in any reasonable form,
 >   or even a vector<int>, or carry out many other essential C++
 >   operations,
 > 
 > - can't debug multiple processes at the same time,
 > 
 > - is slow to start up on large programs, and uses a lot of memory,
 > 
 > - can't let other threads continue to run while one is stopped,
 > 
 > - can't be scripted in a reasonable language,
 > 
 > - or do many other things we all could think of.

This looks like another list that could be added to the wiki that Daniel has
created.

 > ...
 > I want to hear an internals documentation advocate say, "I'm going to
 > work on the internals documentation because I think the date at which
 > user-visible project X is complete will move closer when I do so."

I agree.  I also would like to see a self contained internals manual but I
think it's churlish to expect someone else to write it for me.  Emacs has
no such manual, at all.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: What's an annex? stratum?

[Robert Dewar]

Jim Blandy wrote:

> I want to hear an internals documentation advocate say, "I'm going to
> work on the internals documentation because I think the date at which
> user-visible project X is complete will move closer when I do so."
> 
> I am *not* a seat-of-the-pants coder.  Read prologue-value.h or
> macrotab.h if you want to know my values.  But I know that life is
> short and uncertain, and that the pursuit of beauty has no regard for
> that.

Documentation is not about beauty, though some attention to readability
and nice presentation is certainly worth while. If you follow a policy
of implement now -- document never, you eventually get a mess in which
you find it unreasonably hard to do anything. I find it a bit amazing
for *anyone* to argue in favor of inadequate documentation!

Re: What's an annex? stratum?

[Joel Brobecker]

> Documentation is not about beauty, though some attention to readability
> and nice presentation is certainly worth while. If you follow a policy
> of implement now -- document never, you eventually get a mess in which
> you find it unreasonably hard to do anything. I find it a bit amazing
> for *anyone* to argue in favor of inadequate documentation!

I think you misunderstood what Jim was saying. Jim documents his code
very well, and gives examples of that. What he says is that it's a lot
easier to maintain doco besides the associated code itself rather than
maintain a separate document (which is pretty much what you argued for).
Given the amount of resources that we have, this is probably the most
pragmatic approach to keeping our code documented.

-- 
Joel

Re: What's an annex? stratum?

[Robert Dewar]

Joel Brobecker wrote:

> I think you misunderstood what Jim was saying. Jim documents his code
> very well, and gives examples of that. What he says is that it's a lot
> easier to maintain doco besides the associated code itself rather than
> maintain a separate document (which is pretty much what you argued for).
> Given the amount of resources that we have, this is probably the most
> pragmatic approach to keeping our code documented.

By all means I agree that it is better to have documentation as part of
the source files. Of course the effort of *producing* the initial
documentation is pretty much independent of whether the documentation
is in the source files or in separate files, so when I read:

> Time spent on the internals documentation has, itself, no effect on
> users' experience with GDB.  It's only worthwhile if that time, plus
> the time then spent doing something users *will* notice, is less than
> the time needed just to do something user-visible without internals
> documentation.

It is hard to read into this a viewpoint that says that time spent on
the internals documentation is OK if it is in the source files, but not
if it is in separate files.

I still read the above quoted para as questioning the value of internals
documentation, and to me such documentation is an essential part of any
complex piece of software. But certainly I apologize to Jim if I
misunderand his position.

Re: What's an annex? stratum?

[Jim Blandy]

Robert Dewar <dewar@adacore.com> writes:
> It is hard to read into this a viewpoint that says that time spent on
> the internals documentation is OK if it is in the source files, but not
> if it is in separate files.

You're right; this doesn't make sense as written.

I write the comments in the code before I write the code, because I've
found that the effort of trying to explain what I'm about to try to do
helps clarify my own understanding a great deal.  For me, at least, it
makes enough of a difference that I'm sure I come out ahead, if you
include debugging time.

In other words, if the internals documentation is written before the
code, then, for me, it is a worthwhile investment.  In that case, I do
believe that writing that documentation brings the completion date
closer, and I write it.  I don't know whether other contributors need
this particular crutch; I'm pretty sure some don't.

The only other time I write explanations is when someone asks for
help; here, again, the investment is worthwhile, because someone is
about to go off and write some code, and I can bring their completion
date closer.  Most of what I've contributed to gdbint.texinfo got in
there because Eli liked something I'd written on the mailing list and
asked me to put it there.

Documenting other code after it's designed and written doesn't have
either of these benefits.

I hate arguing against having clear explanations that make the system
transparent to all comers.  Who wants to be the party pooper?  I
brought up the well-commented code I have written as proof that I do
value quality and clarity, not specifically as evidence for or against
internals documentation.  It happens to be evidence for, but only in
specific circumstances.

Re: What's an annex? stratum?

[Robert Dewar]

Jim Blandy wrote:
> Robert Dewar <dewar@adacore.com> writes:
>> It is hard to read into this a viewpoint that says that time spent on
>> the internals documentation is OK if it is in the source files, but not
>> if it is in separate files.
> 
> You're right; this doesn't make sense as written.
> 
> I write the comments in the code before I write the code, because I've
> found that the effort of trying to explain what I'm about to try to do
> helps clarify my own understanding a great deal.  For me, at least, it
> makes enough of a difference that I'm sure I come out ahead, if you
> include debugging time.

I find the same thing, and even more these days, I find I can't rely
on my memory so well, so if I come back to code I wrote 6 months ago,
I need the documentation as much as anyone :-)
> 
> In other words, if the internals documentation is written before the
> code, then, for me, it is a worthwhile investment.  In that case, I do
> believe that writing that documentation brings the completion date
> closer, and I write it.  I don't know whether other contributors need
> this particular crutch; I'm pretty sure some don't.
> 
> The only other time I write explanations is when someone asks for
> help; here, again, the investment is worthwhile, because someone is
> about to go off and write some code, and I can bring their completion
> date closer.  Most of what I've contributed to gdbint.texinfo got in
> there because Eli liked something I'd written on the mailing list and
> asked me to put it there.

certainly fair enough.

One thing that I have found helpful is to ask newcomers to report
as bugs cases in which the code is not clear, and then when the
explanations are given, or the detective work completed, help
write the documentation they found missing.

Re: What's an annex? stratum?

[Eli Zaretskii]

> Date: Tue, 26 Jun 2007 20:42:12 -0400
> From: Robert Dewar <dewar@adacore.com>
> CC: Joel Brobecker <brobecker@adacore.com>, 
>  Markus Deuling <deuling@de.ibm.com>,
>  Eli Zaretskii <eliz@gnu.org>,  pkoning@equallogic.com, 
>  eager@eagercon.com,  stanshebs@earthlink.net,  gdb@sources.redhat.com
> 
> One thing that I have found helpful is to ask newcomers to report
> as bugs cases in which the code is not clear, and then when the
> explanations are given, or the detective work completed, help
> write the documentation they found missing.

We try to do that.

Re: What's an annex? stratum?

[Michael Eager]

Jim Blandy wrote:

> Time spent on the internals documentation has, itself, no effect on
> users' experience with GDB.  It's only worthwhile if that time, plus
> the time then spent doing something users *will* notice, is less than
> the time needed just to do something user-visible without internals
> documentation.

Time spent on internal documentation facilitates others in doing
the work you describe as worthwhile.  If the complaint is that there
are not many people working on GDB, part of the problem, speaking
from experience, is that GDB is fairly opaque.  Flow of control
is convoluted.  The organization of the code tries to be modular,
but that seems often more in the style than the substance.

The alternate "ask a question, we'll be happy to help" tends to
work better in theory than in practice.  The answers seldom provide
much of an overview of operation in an area, nor do they provide the
detail which is commonly included in the documentation.  Frequently,
the answers veer off on tangents (such as this discussion, which
started with a question about what's a stratum, still unanswered)
or into commentary (such as "the new scheme is much better").

> I want to hear an internals documentation advocate say, "I'm going to
> work on the internals documentation because I think the date at which
> user-visible project X is complete will move closer when I do so."

The people who would most profit from improved documentation are
the people who are trying to understand the code.  The people who
are best able to improve the documentation are the ones who have
experience with it.

If you look at improvement in GDB as a single-person effort, then
for the experienced person, it's always better to do it yourself
rather than take the time to facilitate someone less experienced.

If you look at it as a multi-person effort, where an expenditure
of effort on documentation will result in greater improvements
done by more people, then there's greater value.

> I am *not* a seat-of-the-pants coder.  Read prologue-value.h or
> macrotab.h if you want to know my values.  But I know that life is
> short and uncertain, and that the pursuit of beauty has no regard for
> that.

No one is pursuing beauty.  This is the pursuit of utility.


-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Re: What's an annex? stratum?

[Eli Zaretskii]

> Date: Mon, 25 Jun 2007 15:19:32 -0400
> From: Paul Koning <pkoning@equallogic.com>
> Cc: eager@eagercon.com,     stanshebs@earthlink.net,     gdb@sources.redhat.com
> 
>  Jim> I'm even a little skeptical about the value of internals
>  Jim> documentation at all.  It seems to me that explanations like
>  Jim> that belong in the code, where people are more likely to see
>  Jim> them, keep them up to date, and delete them when appropriate.
> 
> That's really unfortunate.  Comments in code are useful but they are
> no substitute for properly written internals documentation.

110% agreement.

But then I'm the guy responsible for the GDB documentation.

Re: What's an annex? stratum?

[Eli Zaretskii]

> Cc: Stan Shebs <stanshebs@earthlink.net>,  gdb@sources.redhat.com
> From: Jim Blandy <jimb@codesourcery.com>
> Date: Mon, 25 Jun 2007 12:10:36 -0700
> 
> Well, let me try again to say what I meant: if you're new to GDB, you
> should not start by reading gdbint.texinfo.  Instead, start by reading
> and grepping, and then experiment by debugging GDB with itself.

That may be the only practical way today, but IMO it's a terribly
inefficient way.  GDB's sources is a hodgepodge of many disparate and
not always related parts: different target-specific back-ends that
have no relation whatsoever, semi-obsolete APIs used by a couple of
rotting targets, features relevant only to remote debugging that are
not clearly separated from the native pieces, etc.  For the
uninitiated, finding one's way in all this maze of twisted little
passages all alike, without some minimal guidance, is a very hard job,
to say the least.

> I'm even a little skeptical about the value of internals documentation
> at all.

I cannot disagree more.  A well written, well indexed internal
documentation can be a real help in studying an unfamiliar program of
GDB's complexity.

Re: What's an annex? stratum?

[Jim Blandy]

Eli Zaretskii <eliz@gnu.org> writes:
>> Cc: Stan Shebs <stanshebs@earthlink.net>,  gdb@sources.redhat.com
>> From: Jim Blandy <jimb@codesourcery.com>
>> Date: Mon, 25 Jun 2007 12:10:36 -0700
>> 
>> Well, let me try again to say what I meant: if you're new to GDB, you
>> should not start by reading gdbint.texinfo.  Instead, start by reading
>> and grepping, and then experiment by debugging GDB with itself.
>
> That may be the only practical way today, but IMO it's a terribly
> inefficient way.  GDB's sources is a hodgepodge of many disparate and
> not always related parts: different target-specific back-ends that
> have no relation whatsoever, semi-obsolete APIs used by a couple of
> rotting targets, features relevant only to remote debugging that are
> not clearly separated from the native pieces, etc.  For the
> uninitiated, finding one's way in all this maze of twisted little
> passages all alike, without some minimal guidance, is a very hard job,
> to say the least.

This is all true.

>> I'm even a little skeptical about the value of internals documentation
>> at all.
>
> I cannot disagree more.  A well written, well indexed internal
> documentation can be a real help in studying an unfamiliar program of
> GDB's complexity.

Well, if GCC's internals documentation is as good as they say, I could
be wrong.

Re: What's an annex? stratum?

[Paul Koning]

>>>>> "Jim" == Jim Blandy <jimb@codesourcery.com> writes:

 Jim> Well, if GCC's internals documentation is as good as they say, I
 Jim> could be wrong.

It is.  I wrote a DFA machine description (instruction scheduler data)
based on gccint.  It was a matter of a few days' work.  There's no way
I would have even attempted such a project if GCC had treated
documentation the way GDB does.

    paul

Re: What's an annex? stratum?

[Eli Zaretskii]

> Date: Mon, 25 Jun 2007 11:31:06 -0700
> From: Michael Eager <eager@eagercon.com>
> CC: Stan Shebs <stanshebs@earthlink.net>,  gdb@sources.redhat.com
> 
> Unfortunately, much of it is obsolete.  Some sections, like 9.6,
> make this explicit.  Other sections say that the area is in flux,
> like section 9.7.  Other sections don't tell you that they are
> out of date (like the section about libgdb?).
> 
> Some important parts are simply missing, like the sections titled
> Console Printing, TUI, Frame Interpretation, Inferior Call Setup, and
> others.

The obsolete parts do not bother me; it's easy enough to mark them as
such, or simply delete them when they are no longer useful at all.
The missing parts are a pain, though.

> If I get to the point where I think I really understand an area,
> I'll be happy to contribute to documentation improvements.

Thanks!

Re: What's an annex? stratum?

[Eli Zaretskii]

> Cc: Stan Shebs <stanshebs@earthlink.net>,  gdb@sources.redhat.com
> From: Jim Blandy <jimb@codesourcery.com>
> Date: Mon, 25 Jun 2007 11:03:39 -0700
> 
> For what it's worth --- we don't invest enough time in
> doc/gdbint.texinfo to keep it a clear, accurate reference to the
> code.  (For me, at least, this is a deliberate decision.)

That's a pity, Jim.  If you can spare even a little bit time, I urge
you to invest it into improving gdbint.texinfo from time to time.  We
don't have too many contributors who are both privy of GDB internals
and capable of writing beautiful docs as you do.

TIA