Re: HeaderDoc style for getter/setter pairs
Re: HeaderDoc style for getter/setter pairs
- Subject: Re: HeaderDoc style for getter/setter pairs
- From: Jerry Krinock <email@hidden>
- Date: Sat, 22 Dec 2007 08:13:54 -0800
On 2007 Dec, 21, at 22:32, Scott Anguish wrote:
Assuming you mean for public consumption?
Yes
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.
_______________________________________________
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