Re: The challenge for Cocoa's on-line documentation
Re: The challenge for Cocoa's on-line documentation
- Subject: Re: The challenge for Cocoa's on-line documentation
- From: Uli Kusterer <email@hidden>
- Date: Sun, 18 May 2008 00:34:10 +0200
Am 17.05.2008 um 23:42 schrieb Gary L. Wade:
I haven't ever used this class, but from just looking it over
quickly, it seems like it's pretty easy to figure everything out.
If you have a problem, just click on the links (e.g.,
NSDatePickerStyle).
While I think the docs aren't as bad as some people make them out to
be, I think there's a lot of room for improvement. They rely too much
on clicking links and reading referenced information to put stuff
together. Let's take NSDatePicker as an example:
<<<
datePickerElements
Returns the receiver’s date picker elements flags.
- (NSDatePickerElementFlags)datePickerElements
Discussion
See “Constants” for a description of the possible values.
Availability
• Available in Mac OS X v10.4 and later.
See Also
• – setDatePickerElements:
Declared InNSDatePicker.h
>>>
It's not at all obvious from this what a date picker element would be
and why I'd need flags for them. If you've played with the date
picker in IB, you'll understand is, but from the docs alone, 'element'
is way too generic, and should be replaced with actual information
instead of just putting spaces in the method name.
Once you click the link 'Constants', though, it becomes clear:
>>>
It's not at all obvious from this what a date picker element would be
and why I'd need flags for them. If you've played with the date
picker in IB, you'll understand is, but from the docs alone, 'element'
is way too generic, and should be replaced with actual information
instead of just putting spaces in the method name.
Once you click the link 'Constants', though, it becomes clear:
<<<
The NSDatePickerElementFlag constants allow you to specify the date
and time elements that the NSDatePickerCell can edit by combining
these constants using the C bitwise OR operator. These values are used
by datePickerElements and setDatePickerElements::
enum {
NSHourMinuteDatePickerElementFlag = 0x000c,
NSHourMinuteSecondDatePickerElementFlag = 0x000e,
NSTimeZoneDatePickerElementFlag = 0x0010,
NSYearMonthDatePickerElementFlag = 0x00c0,
NSYearMonthDayDatePickerElementFlag = 0x00e0,
NSEraDatePickerElementFlag = 0x0100,
};
typedef NSUInteger NSDatePickerElementFlags;
>>>
Of course you wouldn't want to duplicate all information, but I'd
still re-phrase the description for datePickerElements a little:
"Returns a set of flags indicating which visual elements of the date
picker are currently shown, and which won't be usable because they are
hidden."
The simple word 'visual' already clarifies the word 'elements' a lot,
and the mention of shown, hidden and usable hammers home the point
that this view consists of different parts that can be activated and
deactivated at will, without mentioning any of the flags and thus
risking to become outdated as soon as someone adds (or, theoretically,
removes) one of these flags.
Cheers,
-- Uli Kusterer
"The Witnesses of TeachText are everywhere..."
http://www.zathras.de
_______________________________________________
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