Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: email@hidden
- Date: Mon, 11 Jul 2005 14:17:58 +1000
Adding to that list:
THREADSAFE: Must only be called from the main thread. Not
threadsafe!
REENTRANT: no
BLOCKING: yes
I like this formal structure too, but I wonder where you draw the
line... as has been said, a giant table of values like this can be
quite inhibiting to casual readers - although a table of parameters
is still a must-have. In cases where a function blocks for any
significant amount of time, you'd want to know more than just that it
does - you'd need to know why it blocks, what it's doing/waiting for,
etc. A function blocking waiting on the network is a whole different
kettle of fish to one waiting on user input, for example. So the
bottom line is, the function's description really should tell you all
these things anyway. Maybe a new paragraph per topic, even if
they're only a single line, e.g. "This function is not re-entrant."
I would like to see more comments about re-entrancy, though... I've
been bitten only a few times by that, but that's a few times more
than I would have expected. Foundation/AppKit are surprisingly
dangerous to play with, in this regard, since they make huge
assumptions about state through some processes. It's probably quite
hard to document all possible problems in this regard, since you're
talking about a long complex sequence of events, but the odd tip here
and there could save at least one person a lot of frustration. e.g.
"Notification ABC indicates XYZ. You should not change D, E or F
when you receive this notification (as they are still in use by the
notifier)."
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.
A good idea, but providing implementation details limits future
changes... general comments such as "this function is expensive -
minimise use of it" or "function xyz is more efficient in cases
a,b,c", etc are much better. If you give people too much concrete
detail, they'll start making concrete assumptions. But a general
"this is slow" is just a nice hint to try a better way, if possible,
without imposing too strongly an aversion to that function.
Wade Tregaskis (AIM/iChat, Yahoo & Skype: wadetregaskis, ICQ:
40056898, MSN: email@hidden, AV iChat & email:
email@hidden, Jabber: email@hidden)
-- Sed quis custodiet ipsos custodes?
_______________________________________________
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