Date: Tue, 27 May 2008 05:27:15 -0400
From: Andy Lee <[EMAIL PROTECTED]>
[...]
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.
Well, for better or worse, not everyone agrees with you with respect
to whether the physical organization relates to the content.
Personally, I'm with you: even if the entire class remains on a
single page, I think each method should be documented appropriately.
But there are those who argue against adding to the documentation on
the basis of the fact that everything's on one page and (paraphrasing
here) "the docs would just be too long if you added stuff".
Inasmuch as I find docs organized per-page for each class member to
be more appealing, and inasmuch as for _some_ the argument against
fleshing out the individual member documentation is based primarily
on the organization, I see an opportunity to kill two birds with one
stone.
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."
I mean patently obvious to _anyone_ reading the documentation (and
who has the basic language syntax down...I wouldn't have thought that
qualification needed, but based on previous comments in this
discussion, apparently it is :) ). The launchApplication method may
be "trivial", the NSColor class methods that retrieve named colors
definitely are.
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.
We can agree to disagree. IMHO, a code sample, providing some real
context on the use of the method, is very beneficial.
Yes, I know the standard counter-argument: "it's a reference, not a
guide". I simply disagree. Yes, it's a reference. But that
shouldn't preclude the inclusion of code snippets that illustrate the
use of the class member in context.
Even though the method being documented is launchApplication, that
doesn't mean there's no benefit in also documenting in the same place
how you'd use it along with other Cocoa features (such as
LaunchServices, as you point out). Part of the problem of the docs
as they are now is that it's entirely either/or. You either get a
minimalist "here's all the members of the class" view, or you get a
verbose-yet-not-necessarily-relevant "here's a guide for doing
specific tasks" view.
It can be very difficult to switch back and forth between the
enumerative and task views of the documentation, for a variety of
reasons (but in no small part due to the lack of direct links from
the enumerative view to the relevant task view).
Personally, I'd prefer that snippets that are more task-oriented
simply be included directly within the enumerative view, so that the
constant navigating back and forth is avoided. But at the very
least, every class member should have a link to a specific section in
the task view that illustrates the use of the member. When you click
on such a link, it should take you _directly_ to a specific code
example in which that member is used, and the code example's
_primary_ purpose is in illustrating very narrowly the very task for
which that member was intended.
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?
No, the burden isn't on me. As I said, no one ever suffered from
having too many code samples. But lots of people suffer from having
too few. If an error is to be made, it should be made conservatively
by over-documenting, not under-documenting. The burden should be on
the person who insists that the documentation is sufficient without
further elaboration.
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.
Well, I refer you back to my previous statement: the English language
only gets you so far. Code is the one unambiguous, universally-
understood conveyance of a point regarding code.
Yes, it's most often beneficial to have text that elaborates on the
code. In reality, the two combined provide the best illustration.
But if I have to choose between only one or the other, I will go with
a correct code example every time. There is simply too much
variation with respect to how best to express a concept in a human
language for any single human language representation to serve its
purpose for every member of the audience. But every member of the
audience is (should be) conversant in the computer language, and a
code example is in any case inherently unambiguous.
A person reading it may still not "get" the point of the example, but
the code example will always do what it does. That's just how code
works. Any given human language description of something may or may
not sufficiently describe to any given person the information that is
trying to be expressed.
Honestly, I'm surprised to have to reiterate this point. It's a
common enough problem in every communications medium I'm participated
in, and it's a constant refrain in forums such as this one to ask
people asking questions to provide clear, concise code examples
rather than just trying to explain in English what their problem is.
I'd have thought this point was a given.
Pete
_______________________________________________
Cocoa-dev mailing list (Cocoa-dev@lists.apple.com)
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:
http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com
This email sent to [EMAIL PROTECTED]
