Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Dietmar Planitzer <email@hidden>
- Date: Sat, 9 Jul 2005 22:58:26 +0200
On Jul 9, 2005, at 10:06 PM, Scott Anguish wrote:
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:
We are talking about the -setIsVisible: method which is definitely not
listed in the NSWindow reference, although it is a NSWindow method.
Further, the description of the methods you mentioned above do not
contain any cross-reference to -setIsVisible: although it too has to do
with showing and hiding windows. As already mentioned, that's even the
case for -isVisible.
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.
Just like NSWindowScripting is not an informal protocol. It is a
category that contains the implementation of a bunch of NSWindow
methods. The reason why those methods live in their own category has
probably more to do with historic events than planned separation. After
all, that category was originally part of a stand-alone framework, not
part of the AppKit. Thus, back then (in the Rhapsody DR2 days) it in
fact made some sense to have the documentation of that category
separated from the NSWindow document as both lived in two different
frameworks. However, when the category was merged along with all other
AppKit related scripting extensions into AppKit proper, it would have
made sense to also merge the documentation.
Again, either the same principle is applied to all categories and
classes or to none. Inconsistency in the documentation is just as bad
as in the user interface of applications. If NSWindowScripting is
listed among protocols then so must NSExtendedArray. Both are
categories which apply to a particular class namely NSWindow and
NSArray, respectively. Both consist of method declarations and
implementations.
Thus, I still don't see (except for historical reasons) why one is
separated from the documentation of the class to which it relates but
the other isn't.
Regards,
Dietmar Planitzer
_______________________________________________
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