• Open Menu Close Menu
  • Apple
  • Shopping Bag
  • Apple
  • Mac
  • iPad
  • iPhone
  • Watch
  • TV
  • Music
  • Support
  • Search apple.com
  • Shopping Bag

Lists

Open Menu Close Menu
  • Terms and Conditions
  • Lists hosted on this site
  • Email the Postmaster
  • Tips for posting to public mailing lists
Re: running an external app
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


References: 
 >Re: running an external app (From: Peter Duniho <email@hidden>)

  • Prev by Date: Re: Prevent computer from going to sleep but _not_ disable dimming
  • Next by Date: Returning all usernames
  • Previous by thread: Re: running an external app
  • Next by thread: Re: running an external app
  • Index(es):
    • Date
    • Thread