[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Adrian Robert
Subject: Re: Documentation updates and misc. stuff (Was: [Gnustep-cvs] Commit Update)
Date: Fri, 30 Jul 2004 12:15:34 -0400

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

typedef struct autorelease_thread_vars
typedef struct autorelease_array_list

typedef struct _NSHandler
GS_EXPORT void _NSAddHandler( NSHandler *handler );
GS_EXPORT void _NSRemoveHandler( NSHandler *handler );

struct _NSNotificationQueueList;

GS_EXPORT NSRecursiveLock *gnustep_global_lock;


GS_EXPORT void _NSRangeExceptionRaise (void);

extern struct objc_class _NSConstantStringClassReference;

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:

GS_EXPORT NSString * const NSConnectionDidDieNotification;

NSString *NSConnectionDidDieNotification = @"NSConnectionDidDieNotification";


GS_EXPORT NSString*     NSTaskDidTerminateNotification;

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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]