Re: documenting multiple returns

[Pedro Miller Rabinovitch <miller@...>]

On Thursday 23 October 2003 18:44, Reuben Thomas wrote:
> > You're quite correct. I couldn't come up with a different situation where
> > multiple kinds of return are used in at *least* 15 seconds. >: ) Any
>
> Nonetheless, it's still nice to be able to describe return values one at a
> time, in the same way as parameters.

Yes, but now error cases can be treated separately. Something like this:

--| Receives data from a socket
--@ bytes (number) Number of bytes to read
--: (string) Bytes read
--: (number) Number of bytes left in buffer 
--! (string | nil) Bytes read before an error ocurred
--! (string) Error type: "timeout" or "closed"
function receive( bytes )

How does this look? I'm still not 100% sure. The last line could also look 
like this:

--! ( "timeout" | "closed" ) Error type

If the function doesn't return in case of an error (i.e., "throws" the error), 
it would be something like:

--: (string) Bytes read
--! Throws error message

...or something like that. That's still up for grabs.

There's of course a big tradeoff in using more specific data (like "timeout" 
and "closed")... One doesn't need to explain it in the return value purpose, 
but then... Anyway. For now I handle param and return types very loosely, 
i.e., if you want to use 

--@ self (my own object that is mine) Myself

it will work as if 'my own object that is mine' was a natural type name. But I 
plan on using defined types later, which will give us opportunity for 
cross-referencing, yadda yadda yadda.

Cheers,

	Pedro.