Re: running an external app
Re: running an external app
- Subject: Re: running an external app
- From: Andy Lee <email@hidden>
- Date: Tue, 27 May 2008 05:27:15 -0400
On May 27, 2008, at 3:18 AM, Peter Duniho wrote:
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.
"Where do I get an instance?" is exactly the right question, and you
have just explained why the docs for NSWorkspace answer the question
perfectly well. As you are pointing out, it makes no sense to use a
class in the first place unless you understand its purpose in life, so
to speak, and the place to look for that is in class-level
documentation.
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,
I think we should not confuse the physical organization of the docs
with how the content for individual methods is written. And I say
this as someone who prefers to read each method *as if* it had a
dedicated page; it's one reason I wrote AppKiDo.
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.
I'm not sure I understand what you mean by "trivial." To use a method
(assuming I've already read the Overview), I need to know what
arguments to pass (not only their types but their semantics), what the
method will do with those arguments, and what the method will return.
Sometimes one or more of those things can be non-trivial. As it
happens, I think the launchApplication doc does omit something that is
non-trivial, which is how it knows where to find the application to
launch, and I just submitted feedback about that. But this non-
triviality would not be addressed by a code sample; I would expect
something like a link to maybe a LaunchServices doc.
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.
Why not? I don't mean to be argumentative and I certainly don't
believe we are in the best of all possible worlds, but isn't the
burden on you to demonstrate that, say, 40% of NSWorkspace methods
suffer from lack of code examples?
Also, code samples are only one kind of elaboration. Some methods are
elaborated more than others, with or without code samples. Offhand,
my impression is that the longer the method doc, the more likely it is
to contain code samples.
--Andy
_______________________________________________
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