Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Uli Kusterer <email@hidden>
- Date: Mon, 11 Jul 2005 06:59:35 +0200
On Jul 11, 2005, at 6:17 , email@hidden wrote:
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...
I guess this is where the online-database would come in. One could
activate/deactivate what information one is interested in. I agree
that thread-safety and reentrancy statements would be handy.
"Blocking" is too generic. I'd guess that aspect can only be
described in textual docs.
as has been said, a giant table of values like this can be quite
inhibiting to casual readers -
Yes, if this turns into too long a table, it could become
problematic. Of course, if every method call had its own page, it
could just be a small table at the bottom of the page which you don't
have to read.
Maybe a new paragraph per topic, even if they're only a single
line, e.g. "This function is not re-entrant."
Well, it should at least be in the database as a formal, separate
checkbox or so. Then they can experiment with the optimal way to
display the data. Separate paragraphs would only be useful if they
were always in the same spot relative to the whole of the method
description, and if they are, a table would probably work just as
well, if not better.
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.
Yup, though I would only do that in special cases that merit it.
After all, one man's slow function is another man's lightning-fast.
And we don't want to encourage premature optimization.
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