On Tue, Feb 11, 2003 at 01:20:06AM +0100, Martin Nilsson (Åskblod) @ Pike (-) developers forum scribbled:
There is no place for 'usually' in the programming API documentation.
Hey, stop doing context switches! I was talking about the
Hey, they are not that unrelated (I hope)!
documentation, not proposing an alternative wording. Not that
guess what, me too :)
'usually' is forbidden in API documentation ("foobar_sort returns the bytes sorted with the glibc memcmp, usually unsigned char"), but it should obviously be avoided. There is a @throws keyword that should be
glad that we agree :)
used to describe when a function can throw an exception.
But there is no way we are going to see a documentation that has no undefined spots, and in those spots Pike usually behaves as I wrote...
Sure, but that doesn't mean the documentation cannot be improved, does it? If anybody who can corrects one piece of documentation tightening the definitions, the documentation will eventually become a very good one - and that's our common goal, now isn't it?
I can change all that in the CVS, no problem, I'd be glad to do it. But I don't want to (again) step on anybody's oversensitive toes.
There is a profound difference between believing the error messages are broken (which few appearently agrees on) and that they shouldn't
Not broken - ambiguous.
be fixed (which few oppose, I imagine).
again, I'm glad that we agree.
marek