Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Uli Kusterer <email@hidden>
- Date: Mon, 11 Jul 2005 02:23:46 +0200
On Jul 11, 2005, at 1:07 , Steve Weller wrote:
A common thread I see through this discussion is that the
documentation mixes and confuses "what is achieved" with "how it is
done". A big improvement to the docs would be to clearly describe
everything separately in those terms:
Steve,
you're a genius! That is exactly what I've been trying to get a
grip on all this time. Though I'd also add "why" there; the issue
with a good bunch of the docs (at least as of 10.3 -- a lot has
already improved in the current batch) was that they *either*
contained "what" or "how" descriptions. We need both. And we need
"why". And in addition, we also need more information on what certain
methods don't do, or shouldn't be used for and what routines to use
instead. As in:
orderOut:
WHAT IT DOES: Hides the window from view.
HOW IT DOES IT: Takes the window out of the window list.
WHY: Use this to temporarily remove a window from display to quickly
show it again later without disposing of it, or to seemingly close a
utility window of which only a single instance exists.
THIS DOESN'T: Release the window object or remove any data
structures. For that, use closeWindow:. This also doesn't make a
window transparent. For that, see -isOpaque and setAlphaValue:.
In general, I think the reference docs could actually benefit from a
more rigid structure. Instead of embedding parameters in paragraphs
of text, make it a table that clearly labels input/output parameters,
who allocates them or disposes of them, and has links to every data
type of every parameter and what constants may be passed there.
Cheers,
-- M. Uli Kusterer
http://www.zathras.de
_______________________________________________
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