Re: [AD] documenting minor return values

[Peter Wang <tjaden@xxxxxxxxxx>]

On 12 Oct 2001, Eric Botcazou <ebotcazou@xxxxxxxxxx> wrote:
> 
> I respectfully dissent (famous words): why does documenting them imply we
> should be checking them ?

If something says "This returns foo on success, and bar on error."
then I think that I should check it (though usually I don't).

> IMHO the only moral obligation we are under is to
> document the return value of a function that returns a value. Then it's up
> to the programmer to decide whether to check it or not.

Will it really mess with your mind if I say that I agree? :-)


After mastering doublethink, let me have a go at this.

----------------------------------------------------------------------

       int install_timer();

DESCRIPTION
       Installs  the Allegro timer interrupt handler. You must do
       this before installing any user timer routines,  and  also
       before  displaying a mouse pointer, playing FLI animations
       or MIDI music, and using any of the GUI routines.

----------------------------------------------------------------------

Then we tack on one of:

(1)
       The return value is unspecified.

(2)
       Returns zero on success, or a negative number on failure.

(3)
       Returns zero on success, or a negative number on failure
       (but don't bother checking for failure, as it never happens
       anyway).

(4)
       (3) followed by: It's more likely you'll witness the end
       of the universe than see this function fail.

For this case, I'd pick (3).  Or (4) if someone comes up with
something funny.