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

[Richard Frith-Macdonald]

On 29 Jul 2004, at 22:52, Adrian Robert wrote:
> > 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.

Are you *sure*?  It's supposed to simply append them ...ie if there are 
comments in both declaration and definition, you should get both sets 
of comments appearing as the text in the documentation, never any 
overwriting.  I've never heard anyone report that this goes wrong 
before.  The one exception to this is if the comments in the 
declaration and definition are identical ... there is code in there to 
check for that case and ignore one set of comments on the assumption 
that someone has mistakenly copied the same comments into both places, 
or that the same file has been used as both header and source.

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

FWIW, my preference is to put it in the headers.  When I wrote 
autogsdoc I wanted to put it in the source ... because the driving idea 
behind it was to get the documentation absolutely as close as possible 
to the code people are writing, to make it as easy as possible for them 
to add documentation (on the theory that that's the way to get them to 
write it).
I think experience in the past year has shown that the theory was wrong 
... people who add documentation will add it either way, people who 
don't  add documentation just don't.  That being the case, I think it's 
more natural to have the comments in the header, and maybe at some 
future time autogsdoc can be made simpler and more efficient by ceasing 
to parse the source and sticking to the headers only.

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

Yes ... the person adding comments must normally make sure they 
document only one version of the code.
Where multiple comments are found for something being documented, they 
are merged together ... so if
there are multiple versions of an item, either you should comment only 
one version or, the comments in
each version should make it clear that they are referring to different 
variants of the code.  This has a legitimate
use if you want to document the differences in implementation or 
behavior in different variants of the code,
but I'd suggest that it should be a *strong* recommendation that people 
only document the first variant
of any conditionally compiled code.

> If autogsdoc is changed to not throw away declaration comments on 
> reading implementation comments

It doesn't... except where the two comments are identical ... in which 
case it keeps one copy.

>  (or lack thereof) this might fix most of this problem.  Autogsdoc 
> does not parse #ifdefs,

It does parse them ... but only to tell what standard is in effect, not 
to say whether or not comments are to be used.

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

The rule about what is to be documented is simple ... it will document 
*everything* in the header files you give it on the command line (with 
a minor ivar exception) .  It will also append any further information 
it finds in inferred implementation files which corresponds to items in 
the headers.

eg. If you tell it to document NSObject.h, it documents everything in 
that header.  It also looks at NSObject.m and appends any autogsdoc 
markup found in that file to the documentation of things which were 
already found declared in NSObject.h

Basically this follows the visibility rules of ObjC ... you can see 
everything in the public header, so it documents everything in the 
public header.  Information from the private source code is just added 
to the entries already generated for publicly declared items.

You can also use autogsdoc to document source files with no public 
header files, by supplying the source file name on the command line ... 
in which case autogsdoc treats it as if it were a public header file.

Autogsdoc uses the same rules as the Objective-C language for 
determining if an ivar is private or not.
ie if it is declared as '@private' then it is private (and not 
documented by default).

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

Autogsdoc has command-line options to say whether instance variables 
are all to be documented or not.
The leading underscore convention for ivars determines whether a 
warning will be inserted into the documentation when such an ivar is 
documented, not whether it is documented at all.
It's the commend-line option that says whether private ivars should be 
documented.

I think it's quite likely that in many cases the problem is that ivars 
are not being declared as @private when they really ought to be (in 
ObjC, ivars are @protected by default), and the documentation generated 
by autogsdoc is simply reflecting an error in the header files.

I don't see any need to ignore anything ... if something should not be 
documented, it shouldn't be in the header file.
The solution should be to correct the header files in such cases.