Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Dietmar Planitzer <email@hidden>
- Date: Sun, 10 Jul 2005 11:07:54 +0200
On Jul 10, 2005, at 6:07 AM, Scott Anguish wrote:
On Jul 9, 2005, at 4:58 PM, Dietmar Planitzer wrote:
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.
As I said, it's actually an informal protocol. NSWindow does
implement it, and I agree (and have raised the issue internally) that
informal protocols should be listed along with formal protocols in the
class documentation.
Still I continue to claim that NSWindowScripting is not an informal
protocol but a category. The reason why I do this is because I try to
apply the definition of an informal protocol as I learned it back in
the OpenStep days. When I do this I always come back to the same
problem: NSWindowScripting fails to satisfy the definition.
Now what are the definitions of a category, informal protocol and
formal protocol I'm using here ?
Category: A category is a list of methods which are added by the
runtime to an existing class. It can come in two different flavors:
1) Declarations only
2) Declarations and implementations
Informal protocol: Is a category of flavor (1), thus it consists of
declarations only. Further, an informal protocol is de facto always
declared on the canonical base class NSObject in order to emphasize the
fact that any class may adopt methods of the informal protocol. The
fundamental difference between an informal protocol and a formal
protocol is that the former allows the adopting class to implement
methods selectively. Therefor, the user of an informal protocol can not
be sure that all methods are implemented and must check via
-respondsToSelector: whether the adopter has implemented a certain
method or hasn't.
Formal protocol: Consists of declarations only. The important
difference to informal protocols is that all methods in the protocol
must be implemented by an adopting class.
So, these are the definitions I'm using here, which I openly admit may
be a bit pedantic (but then what good for would be all the math classes
you have to go thru when you're at University, if not for learning to
be pedantic :).
Now, I've entered the term "informal protocol" into the search engine
available at the Apple Dev side and got a lot of hits but no hit that
gave a clear, unambiguous definition of the term informal protocol and
how it exactly relates to the term category. Doing the same with Google
gives you a lot of hits where sometimes the term "informal protocols"
is used in the context of the definition above, sometimes as a synonym
for categories.
But if the term informal protocol is supposed to be just another word
for category, why then was it invented ? After all if it's just a
category than call it a category - no need for yet another term that
may just add unnecessary confusion to a simple concept.
However, as far as I remember the term informal protocol was invented
because the use of a category that contains declarations only and which
is used in the same spirit as a formal protocol is conceptually
something different than a category which is used to add new method
implementations to an existing class.
After all, there must be a reason why one is called informal, the other
formal, but both bear the word "protocol" in their name, suggesting
that for both the fundamental idea is the same. Namely, declaring an
interface to be used by a protocol user and a protocol adaptor.
Finally, I want to mention that the use of the word protocol in the
term informal protocol, at least in the case of German, implies that it
is a description, but not an implementation. You can implement a
protocol, but a protocol is not an implementation. It, however, can be
used as the description of how to implement something. Again, that's
how the word protocol is commonly used in German, it may be different
though in the case of English.
Anyway, I think it's time that the documentation gives a clear
definition of those terms and uses the terms consistently according to
their definition.
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.
If you simply look at the headers, then yes the appear the same.
However the informal protocol methods are intended to be overridden.
The NSWindowScripting method -isResizable is intended to be overriden ?!
No, all except for three methods in that category are clearly intended
for simple, good old, straight-forward usage aka calling just like it
is the case for any of the NSArray categories. You certainly may
override them in an NSWindow subclass but you are not required to do so
in order to get useful behavior out of them.
Again, please don't make simple things more complicated than necessary.
People do not go to the documentation looking for a method for the
problem they are currently working on with a huge list of special rules
and exceptions in their minds. Rules like:
Is this an informal protocol intended for subclassing or using ?
Is this method somehow related to AppleScript or not ?
Was this method added in Rhapsody DR2, before that or after that ?
Was this method implement in its own framework or in the AppKit ?
Was this method originally implemented in its own framework but got
merged into AppKit later ?
etc.
etc.
No, they have an object they want to work with, like a window, and a
problem aka an action they want to execute on the object, like showing
or hiding a window or whatever. Thus, they most likely go to the
NSWindow reference document and expect to find all methods dealing with
NSWindows there. And I may add that they expect this rightfully.
Finally, I again must point out that we still have an unexplained
inconsistency:
Why is NSWindowScripting in the protocol section, but
NSApplicationScripting and NSTextStorageScripting are not ?
All three categories are about AS support. That's the original reason
for their implementation. All three reside in a dedicated header file.
All three consist of declaration and implementation. All three have
methods which are useful on their own and some which are only useful if
you subclass them. All three even share the same category name
"NSScripting". All three are declared on particular classes - not
NSObject. Finally, all three categories have methods which are useful
outside of the narrow AS context.
The only difference is that NSWindowScripting methods are documented in
their own file, while the description of the methods of the other two
categories are merged with the documentation of the classes to which
they belong. Why that difference ?
Further, have you noticed that the real name of the category is
actually NSScripting, not NSWindowScripting ? Why does the
documentation list a category name that if entered into the
project-wide find & replace panel in Xcode will give you no hit in the
AppKit headers ? I've tried it just now, two times even. Searching for
NSWindowScripting in the headers results in no hit. However, it works
as expected with all the other protocol and informal protocols listed
in the AppKit protocol section. Why that difference ?
And finally, why does the NSWindow reference document contain not a
single reference to any of the methods in the NSWindowScripting
document ?
Sorry but this is simply inconsistent and illogic.
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