Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Shaun Wexler <email@hidden>
- Date: Sun, 10 Jul 2005 20:48:59 -0700
On Jul 10, 2005, at 5:23 PM, Uli Kusterer wrote:
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.
Adding to that list:
THREADSAFE: Must only be called from the main thread. Not threadsafe!
REENTRANT: no
BLOCKING: yes
Maybe some other comments as to the relative costliness of the
function (recommended alternatives and/or other considerations), and
possibly some insight as to the underlying implementation details,
such as "makes three round-trips to CGS", or "wraps a low-level
Carbon function", etc. Anything to promote efficiency of use.
--
Shaun Wexler
MacFOH
http://www.macfoh.com
_______________________________________________
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