There is no place for 'usually' in the programming API documentation.
Hey, stop doing context switches! I was talking about the documentation, not proposing an alternative wording. Not that '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 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...
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 be fixed (which few oppose, I imagine).
/ Martin Nilsson (Åskblod)
Previous text:
2003-02-11 00:41: Subject: Re: Implicit vs. explicit type casting with Pike
[snip]
Undefined behaviour usually means one of these:
^^^^^^^
- Nothing happens (possibly returning 0 or -1 depending on situation)
- An error is thrown.
- Pike dumps core.
There is no place for 'usually' in the programming API documentation. It's an 'either-or' situation, no 'maybe-perhaps'. The error conditions, the calling conditions, the expectations as to the parameters must be documented unambiguously and clearly. It isn't that hard to add another sentence to the documentation:
If an object does not contain the _m_delete method, an error will be thrown.
or just change the 'if' to must in the current sentence. And:
Returns The value that was removed will be returned.
Not a word about an error. Another source of uncertainty. For the record - 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.
Or is my English failing me again?
It could be logic this time :)
I wish it was, but I'll be bold enough as to disagree :)
marek
/ Brevbäraren