Re: Documentation updates and misc. stuff (Was: [Gnustep-cvs] Commit Update)

[Adrian Robert]

Hi,

Thanks for the feedback.


> A big comment on something I noticed about halfway through the patch:
>
> > +Nonetheless, the recommendation of this author is that you put the 
> > comments
> > +in the header,
>
> Regardless of opinions about this, it's very important that everything
> is documented only once, and this doesn't seem to be the case with your
> patch. I, too, prefer to have the documentation in the headers, but the
> fact that we only have one copy of each bit of documentation is much
> more important than its location. This should be fixed as soon as
> possible (before the two copies diverge and there's time-consuming
> merging to do).

You are right.  The problem is in some cases autogsdoc either 
overwrites comments made on a declaration with those later found in a 
definition (clearing them if the comments are "blank"), or it just 
ignores the comments on the declaration.  I have been meaning to look 
at the code and try to fix this, but in the meantime I would sometimes 
just lazily copy the comments to the place where they would get picked 
up.  Bad, yes..

Regarding any duplication introduced between source and header (I don't 
think there is much, I tried specifically to avoid it), I had vaguely 
in mind that at some point in the not-distant future a policy could be 
decided for whether to put gsdoc comments in headers and source (and 
hoping myself for the headers option), then we would just move/merge 
everything accordingly.  In the long run we need such a policy to ease 
maintenance.

For duplication _within_ a header file like NSZone.h as you mentioned 
I'll either fix autogsdoc soon (or maybe Richard will volunteer to look 
at it ;) or do another pass and take out the comments that are not 
getting picked up anyway.  There were not very many instances of this, 
I think just NSZone and NSGeometry primarily..


> This also applies if there are several implementations eg. due to
> #ifdef:s; there must still only be one copy of the documentation.

If autogsdoc is changed to not throw away declaration comments on 
reading implementation comments (or lack thereof) this might fix most 
of this problem.  Autogsdoc does not parse #ifdefs, most of which in 
Foundation relate to the NO_GNUSTEP, etc. standards selectors.  If we 
tried to deal w/the multiple implementations issue by running the C 
preprocessor before generating docs, this would prevent generation of 
docs that include all standards.

You mentioned some things are now documented that are "private".  I 
don't understand the structure of GNUstep headers very well, nor how 
autogsdoc decides whether something should be documented or not.  It 
does NOT decide based on the presence of "/** ... */", but rather based 
on its own criteria and it puts markers in the docs with "Description 
forthcoming..." if there are no "/** ... */" comments.

This is a good feature of the doc system (developer does not have to 
consult the header directly even if the provider did not document some 
things), but maybe it sometimes makes the wrong decision, or maybe some 
stuff in the Foundation headers should be elsewhere?  Ideally, the only 
stuff appearing in Headers/Foundation/*.h should be public, with the 
private stuff moved to "hidden" headers under Source.  This works well 
for instance variables (using the GSXxx classes in cluster patterns) 
but may not be possible for these other variables due to implementation 
constraints.

A related question is the meaning of the "Variables" category in gsdoc. 
 A lot of the things that autogsdoc is classifying as "Variables" 
actually appear to be "Constants" in terms of their usage, e.g., fixed 
strings for notification types.  Most of the others are the ones you 
said should be "private".  Is "Variables" supposed to be "global 
variables"?  If so, we need to look at what criteria autogsdoc uses to 
distinguish one from a "constant", and check whether this is in line 
with the declarations in the Foundation headers.

As an additional measure, we may want a way to mark something for 
autogsdoc to ignore, like a special '<ignore/>' tag.  (Just looking for 
underscores and things like that in an identifier runs the risk of 
running up against someone's programming conventions, which is why 
autogsdoc does not completely hide such ivars/methods now.)

Thanks for the (extensive!) other suggestions you gave, I will try to 
implement most of them..

Adrian