Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Scott Anguish <email@hidden>
- Date: Sat, 9 Jul 2005 16:06:13 -0400
On Jul 9, 2005, at 8:16 AM, Dietmar Planitzer wrote:
I don't see how breaking up the documentation of a single class
into multiple individual documents is of any help. In fact I think,
and as this sub-thread has shown, it makes it harder to find what
people are looking for. Consider again the original problem:
We are looking for the documentation of a method that allows us to
show/hide a window.
actually, this documentation IS in NSWindow.
makeKeyAndOrderFront: and orderOut:
There are exactly two important keywords in the problem statement
above: showing/hiding and window. Therefor, it's most likely that
the person who is looking for documentation on his problem is going
to look into the NSWindow reference and looking for methods having
to do with showing and hiding windows. The last thing we can expect
is that everyone has a list of each and every category stored in
his mind which would allow him to instantly know where exactly to
look for the documentation of a particular method.
This is the simple reason why _all_ methods of a class, no matter
if they are for whatever reason declared in a category or not,
should be listed in the reference of that class without exception.
Further, applying this logic to all Cocoa classes, we get a
problem: If methods declared in a category are supposed to be
documented in their own document, why does this not apply to
classes like NSArray, which are split up implementation-wise into
many different categories, but still all methods are described
together in one single reference document ?
because those aren't informal protocols.
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden