Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: mmalcolm crawford <email@hidden>
- Date: Sun, 10 Jul 2005 19:59:28 -0700
On Jul 10, 2005, at 5:23 PM, Uli Kusterer wrote:
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:
[...]
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:.
A very interesting suggestion, thank you (both).
I particularly like the "This doesn't" aspect, although I'm not sure
how generally applicable it might be. It relates to something else
I'd *personally* (and speaking for myself only) like to see (and
write <sigh>) more of -- what not to do. In many cases the
documentation describes part of a potential solution space, but then
doesn't put any bounds on it. When I've described this before I've
given the analogy of Winston's arch learning program. Unless you
tell the application what is not an arch, it overgeneralises (best
reference I can find at the moment: <http://www.rci.rutgers.edu/~cfs/
472_html/Learn/Winston.html>).
The main concern I have is the "how it does it" section. This may be
useful in some cases, but again I'd be hesitant to give too many
implementation details since the implementation may change, and
encapsulation is an important aspect of Cocoa and OOP in general.
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.
I'll take that as another vote for the CF-style parameter description
in the informal poll :-)
mmalc
_______________________________________________
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