From maintainers-request at octave dot org Fri Dec  3 23:40:44 2004
Subject: Re: file-io docstrings
From: Paul Kienzle <pkienzle at users dot sourceforge dot net>
To: octave maintainers mailing list <maintainers at octave dot org>
Date: Sat, 4 Dec 2004 00:40:53 -0500


On Dec 3, 2004, at 9:30 AM, John W. Eaton wrote:

> In most places, if a function only returns one value, the docstrings
> have
>
>    at deftypefn {Built-in Function} {} fflush (@var{fid})\n\
>
> instead of
>
>    at deftypefn {Built-in Function} {} @var{status} = fflush 
> ( at var{fid})\n\
>
> as in your changes, so I removed the " at var{status} = ".  But we should
> decide what the convention should really be.  I think it clutters the
> docs to have the return values listed by name when there is only one,
> but maybe others would prefer to see them.
>
> Comments?

Some routines don't return values, and some routines do different things
if a value is returned than if one isn't.

I'm not convinced this is enough of a reason to increase the clutter on
in the documentation though.

- Paul