Re: running an external app
Re: running an external app
- Subject: Re: running an external app
- From: Peter Duniho <email@hidden>
- Date: Tue, 27 May 2008 00:18:55 -0700
From his comments, it's possible Johnny Lundy's point is different
from the one I'd take away from his example. I'll let him speak for
himself on that point. But IMHO there _is_ a valid point in here
somewhere. In particular...
Date: Mon, 26 May 2008 23:29:28 -0400
From: Johnny Lundy <email@hidden>
[...]
Now the line
- (BOOL)launchApplication:(NSString *)appName
May be technically the declaration of the method, but is that really
useful to anybody? After all, you do not declare this method in your
code; you just invoke it. I can't tell you how many times I have been
led astray by this terminology - took me at least a year to figure out
that the way it is written has nothing to do with how you use it.
I'd agree that's an odd statement. How can you program in Objective-
C without recognizing a method declaration and also knowing what that
means with respect to calling that method? In this aspect, the other
comments about Nathan needing to become more familiar with Objective-
C are correct.
The way you would use it is something like
(BOOL) loadedIB = [[NSWorkspace sharedWorkSpace] launchApplication:
@"Interface Builder"];
Which bears no resemblance to the line that is written in the
documentation.
Nor should it. It's common (I might even say ubiquitous) to document
the method declaration, not the usage.
So, where's the valid point in all of this? Here...
This OP is NEVER going to figure that out from the line in the
documentation. Even the "discussion" goes on and on about .app
extensions and what notifications the method sends, but never mentions
how to invoke the thing.
This is why they need to put at least one line in every one of these
method documentations to show how it is invoked.
I'm not sure that _every_ method needs a code sample demonstrating
how to invoke it. Do we really need the docs to include a code
snippet to demonstrate how to invoke each of the NSColor class
methods to create named colors?
But I certainly think there'd be some value in a code snippet for a
less-trivial method such as NSWorkspace's launchApplication. Of
particular note is the question of "well, this is an instance
method...where do I get an instance?"
Now, as it happens, NSWorkspace has a perfectly useful example, in
the "Overview" section of the documentation. Frankly, while I'd
prefer "one method per doc page" documentation, with more detailed
descriptions and more code samples, in the context of the docs as
they are today, there's a readily accessible example of how to get an
instance of NSWorkspace in the very part of the docs anyone ought to
be reading before they try to use the class.
But if the docs were fixed (admittedly, that's "fixed" in my own
sense of the word :) ) so that each method had a dedicated page, even
though the "Overview" page would still have the same example the
section has now, it wouldn't be all that unreasonable to expect a
code sample for all but the most trivial methods that includes
typical usage (and in this case, that would include demonstrating
where you'd get the instance). And frankly, I don't see what would
be so bad about including such examples on all but the most trivial
examples even as the docs are now.
I expect replies to the effect of "it would bloat the documentation",
etc., but the fact is, that single example could clarify 1) That you
have to message the sharedWorkspace instance, and 2) That you don't
actually code "- (BOOL)launchApplication:(NSString *)appName".
I really don't get the #2 point here. I agree with the others: if
you don't already understand #2, you don't know anything at all about
Objective-C. These reference docs aren't the place to learn that.
But point #1 seems more reasonable to me, especially in my utopian
world of "one page per method" documentation. :) I've seen the
"it's a _reference_, it doesn't need that kind of bloat". But I
simply will have to continue to agree to disagree with those who say
that. For methods like this, it's a tough call as to whether they
are trivial enough to not need a specific code example. And if it's
a tough call, IMHO the call should come down in favor of more
documentation, not less.
You leave out the code samples only when it's absolutely obvious they
aren't needed. No one ever ran into a brick wall by having too many
code samples, but plenty of people run into a brick wall for want of
code samples.
The launchApplication method is definitely right on the edge. It is
_so_ close to being a trivial method, that I'd be willing to accept,
for that specific method, an argument that it's too trivial to need a
code example. But, there's not a single code example in the entire
NSWorkspace documentation, except for the one in the "Overview", nor
are there links to code samples that might be found elsewhere. You
can't tell me that _every_ method is so trivial that it needs no
elaboration.
A verbal description of a method is well and good, and should of
course be as descriptive and useful as possible. But as anyone who
has tried to answer a coding question via email (which describes a
number of people reading this message) should know, the English
language only takes you so far. One line or a few lines of code
speaks volumes and sometimes understanding is vastly more difficult,
if not nearly impossible, without that.
I again eagerly await the uniform dismissal of my opinion. :)
Pete
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden