Re: HeaderDoc style for getter/setter pairs
Re: HeaderDoc style for getter/setter pairs
- Subject: Re: HeaderDoc style for getter/setter pairs
- From: Steve Weller <email@hidden>
- Date: Sat, 22 Dec 2007 08:44:44 -0800
On Dec 22, 2007, at 8:13 AM, Jerry Krinock wrote:
On 2007 Dec, 21, at 22:32, Scott Anguish wrote:
It's best to go the way we do now (although writing these daily
that may have been pounded into me)
getters and setters can have different usages notes that are
complex to note if they're together.
Fair enough, but what if, on the other hand, the getter and setter
are dumb and simple, but the instance variable itself requires some
@discussion. Here's an example:
/*!
@method disallowedCharacterSet
@abstract gets the 'disallowedCharacterSet' of the receiver
@discussion This class defines a 'disallowedCharacterSet'. If,
while typing in a new
token, the user enters a character from the
disallowedCharacterSet, it will be replaced
with an underscore ("_"), and the System Alert will sound. The
user may continue typing
after this happens.
@result The 'disallowedCharacterSet' of the receiver
*/
- (NSCharacterSet *)disallowedCharacterSet ;
/*
@method setDisallowedCharacterSet:
@abstract sets the 'disallowedCharacterSet' of the receiver
@discussion This class defines a 'disallowedCharacterSet'. If,
while typing in a new
token, the user enters a character from the
disallowedCharacterSet, it will be replaced
with an underscore ("_"), and the System Alert will sound. The
user may continue typing
after this happens.
@param The new 'disallowedCharacterSet' for the receiver
*/
- (void)setDisallowedCharacterSet:(NSCharacterSet *)newValue;
I hope you can appreciate why it might make more sense to me to
describe the instance variable elsewhere, and have the getter and
setter documentation simply reference it.
I believe that we have to define the instance variable as some
entity, in this case 'disallowedCharacterSet', to show the
connection between the setter and the getter. But since the getter
and setter documentation are separate, I repeat the same
@discussion in each. Is this really the correct way to write it?
If not, please edit and show the way you would write it....(Scott
or anyone else).
As opposed to alphabetical order?
If they shared a common @discussion, it would make sense for setter
to immediately follow getter.
Yes it would. In fact the list should not be in alphabetical order,
but in "cocoabetical" order. In other words, strip off the "set",
"is", "countOf" and all other constructions that serve to scatter
understanding of the underlying logic of the object property, sort by
what is left, and list all the applicable methods together with a
description of that property.
The other useful change would be to omit almost all documentation for
setters and getters. There is a large amount of noise present because
of "Sets the foo object" and "Returns the foo object" kind of
explanation. In most cases all that should be listed are the
@properties lines lifted straight from the .h file and pasted into a
very small section called "Setters and Getters".
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden