Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Dietmar Planitzer <email@hidden>
- Date: Sat, 9 Jul 2005 14:16:35 +0200
On Jul 9, 2005, at 9:44 AM, Scott Anguish wrote:
On Jul 9, 2005, at 2:33 AM, James Andrews wrote:
Actually, I didn't dig in in NSWindowScripting.h. I didn't know
NSWindowScripting existed, as my Cocoa/Obj-C books never talked about
them. I found it defined in the NSWindow section of the "Cocoa in a
Nutshell" book where they say it's an Accessor Method of NSWindow
(though thumbing through and finding NSWindowScripting it is also
listed there).
Right, well, in this case I'd say it's an issue with Cocoa in a
Nutshell.
NSWindowScripting is an informal protocol, and those are separated
out as categories.
Well, I personally still don't understand why the methods defined in
the NSWindowScripting category are not documented in the NSWindow
reference ?
They are after all methods of the NSWindow class, even if they are
declared in their own category (which must not even imply that they are
indeed defined in a dedicated category).
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.
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 ?
Well, I think it's in fact easy to explain this inconsistency: the
NSArray docs where written back in the OpenStep days while the
NSWindowScripting category was added much latter. Apparently whoever
wrote the NSWindowScripting documentation did not even update the
NSWindow reference with the necessary cross-references. I.e. the
-isVisible method, which is clearly the logical companion of the
-setIsVisible: method, does not even contain a reference to the latter.
Funnily enough it contains a reference to the obviously more relevant
-visibleRect method of NSView.
As for "I think Objective-C categories present a bit of a unique
challenge for doc writers is all".
writing the doc isn't any different...
I think providing the inherited informal protocols for things
would be good, Right now we document the formal protocols in the
'table' at the top of the class.. the name of the protocol and, if it
is from a superclass, the superclass in brackets. The same thing
could be done with informal protocols.
No, no, please don't do this.
This kind of information would not be of any help. It would not help me
to find the documentation of a method faster, it would not help me to
make my program better or faster in general. It would however blow up
the inheritance section in terms of size of many classes to the point
where it would become quite hard to find the actually relevant
inheritance information: namely the list of super-classes. Just
consider what it would mean for the inheritance section of the NSArray
class. This is a case where the principle that "more is not necessarily
better" should be taken note of.
I personally think that while informal protocols or categories are a
good organizational tool on the implementation level, they are not much
if not of no relevance on the documentation level. I think that the
organization of the documentation of a particular class in terms of its
categories does not help the documentation, does not make it easier to
understand or find information. In fact I think they unnecessarily make
it harder to find information on that level.
And in any case let's keep in mind that even from the viewpoint of the
ObjC runtime, categories have basically no relevance after they are
loaded into an executable. All methods defined in an category are
merged into the class which the category overloads right at the time
the category gets loaded. Thus, from the viewpoint of the ObjC runtime
every method in a category is a proper part of the class to which the
category applies.
There is no reason why the documentation should make an (artificial)
distinction that not even the runtime is making.
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