should obviously be avoided. There is a @throws keyword that should
^^^^^^^ (Though, it isn't documented in refdoc/keywords.txt... :)
Sure, but that doesn't mean the documentation cannot be improved, does it?
Somewhat more serious mode: I think you should really think deep thoughts about this past discussion and contemplate why it is this forum often explodes when you start a thread. Niels tried to prevent it from racing early on, and we all share the fault for having this heated, fun and fairly unconstructive discussion. There is no better way to trigger the reply button at smart people than implying that they are stupid (see quote above). A good start is to avoid retoric questions. They are almost only useful when you are more interested in winning a debate than convincing the opponent. Or, as my teacher in philosophy said; Who needs retoric questions?
/ Martin Nilsson (Åskblod)
Previous text:
2003-02-11 01:46: Subject: Re: Implicit vs. explicit type casting with Pike
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
/ Brevbäraren