Re: The challenge for Cocoa's on-line documentation

FROM : Uli Kusterer
DATE : Sun May 18 00:34:10 2008

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