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

[Adrian Robert]

On Jul 30, 2004, at 3:07 AM, Richard Frith-Macdonald wrote:
> > 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 looked at the code and you seem to be right.  I may have been getting 
confused in cases like the following, in NSZone.h:

typedef struct _NSZone NSZone;

... some other declarations ...


struct _NSZone
{
...
}

Autogsdoc picks them both up, and assumes they are separate.  The 
typedef ends up under "Types", while the struct declaration is going 
into "Variables" (then I would only see one at a time, add comments to 
the other, and wonder what was happening).  Anyway, this may be an 
autogsdoc problem, since it seems like the two should be consolidated, 
or even if not both should go into Types -- neither is a "variable".  
As far as the header structure, I don't know enough about it to say 
whether this separation of the struct and typedef is necessary, but I 
assume it is.


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

Anyone else have opinions on this?


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

This issue is not occurring so much with ivars, of which there are very 
few in the Foundation headers, but rather with various functions and 
auxiliary variables.  Here is the list of things that Alexander said 
probably ought to be private:

NSAutoReleasePool.h:
typedef struct autorelease_thread_vars
typedef struct autorelease_array_list

NSException.h:
typedef struct _NSHandler
GS_EXPORT void _NSAddHandler( NSHandler *handler );
GS_EXPORT void _NSRemoveHandler( NSHandler *handler );

NSNotificationQueue.h:
struct _NSNotificationQueueList;

NSObject.h:
GS_EXPORT NSRecursiveLock *gnustep_global_lock;

NSRange.h:

GS_EXPORT void _NSRangeExceptionRaise (void);
#define GS_RANGE_CHECK(RANGE, SIZE)
#define CHECK_INDEX_RANGE_ERROR(INDEX, OVER)

NSString.h:
extern struct objc_class _NSConstantStringClassReference;

NSValue.h:
typedef struct { ... } GSNumberInfo;
GSNumberInfo    *GSNumberInfoFromObject(NSNumber *o);
unsigned        GSSmallHash(int n);

Being unfamiliar with the Foundation codebase and the OpenStep spec, 
I'm loathe to make final decisions on or tackle these myself.  Is there 
anyone willing/able to look at them?  We could do one pass, then look 
again at what shows up in the autogsdoc HTML, and decide if anything 
else should be hidden.

A related issue seems to be with coding style.  For instance, some 
notification string constants like NSTaskDidTerminateNotification 
appear in "Variables" while others such as 
NSConnectionDidDieNotification occur in "Constants" is because of a 
difference in declaration:

NSConnection.h:
GS_EXPORT NSString * const NSConnectionDidDieNotification;

externs.m:
NSString *NSConnectionDidDieNotification = 
@"NSConnectionDidDieNotification";

but


NSTask.h:
GS_EXPORT NSString*     NSTaskDidTerminateNotification;

NSTask.m:
NSString *NSTaskDidTerminateNotification = 
@"NSTaskDidTerminateNotification";

It would be best to normalize such declarations to the first type (and 
record the decision as a coding standard somewhere).  If consensus 
arises I'm happy to take care of this kind of thing in the code and 
make an addition to the Coding Standards document.

However, if there is going to be a release of Base soon we should 
postpone all such housecleaning code changes until afterwards, for 
obvious reasons.

Adrian