Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Dietmar Planitzer <email@hidden>
- Date: Sun, 10 Jul 2005 11:01:34 +0200
On Jul 10, 2005, at 12:25 AM, Greg Titus wrote:
On Jul 9, 2005, at 2:09 PM, Dietmar Planitzer wrote:
However, in the case of the NSWindowScripting category separating the
documentation doesn't make sense. Both NSWindow and NSWindowScripting
are implemented by the AppKit as it is today. In both cases we're
dealing with methods belonging to the same class, namely NSWindow.
Further, NSWindowScripting is not an informal protocol in the sense
that you as an application developer would be expected to implement
any of the methods declared in that protocol unlike say
NSDraggingDestination That's why I would not even call it an informal
protocol. Thus, having NSWindowScripting in the AppKit protocol
section does not make sense. At least not in my view.
Actually, I would argue that NSWindowScripting is much closer to an
informal protocol like NSDraggingDestination than it is to the rest of
the methods in NSWindow, and therefore ought to be documented
separately.
NSWindowScripting is a bunch of methods which should generally _not_
be called from code. They are methods that duplicate other existing
functionality on NSWindow, and exist only as a separate 'interface'
for AppleScript to call. You only need to be aware of methods like
-setIsVisible: if you are subclassing NSWindow and need to have some
kind of different behavior when the "is visible" property is set from
AppleScript. So since they aren't intended for calling in code and
only for subclassing, it is very like an informal protocol with an
existing default implementation.
Sorry, but I disagree. I disagree because there is no good reason why
an application shouldn't call a method like NSWindowScripting's
-isResizable which is definitely easier to use than -styleMask and
keying off the resizable attribute from the returned style bit mask. In
fact I personally prefer -isResizable over the -styleMask technique as
it makes it absolutely clear in the code what we're doing, also it's
easier to write and read and above everything else it even works with
KVC.
Honestly, I don't understand why such a special case is made out of the
NSWindowScripting category. None of the methods in that category are
any more special than any other NSWindow method, except obviously the
three (out of 15) which deal with the interpretation of script
commands. They can be used without sub-classing and they don't crash
your app just because you don't call them from an AS handler. Sure,
those methods were added in the context of adding general AS support to
the AppKit, but trying so hard to limit their use just to AS because of
this is something I can not agree with.
But even when I apply your logic consistently to the other scripting
related categories that were added at the same time to the AppKit,
namely NSApplicationScripting and NSTextStorageScripting, we again run
into a problem: why are the methods of those scripting related
categories documented in the reference documentation of the classes to
which they apply (NSApplication and NSTextStorage), but not so for
NSWindowScripting ?
I'm sorry but there is obviously (to me) an inconsistency in the
organization of the documentation that needs to be address.
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