file-io docstrings

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

file-io docstrings

Teemu Ikonen
Hi,

I made some cleanups to the documentation strings on functions defined on
file-io.cc. A patch is attached.

Teemu

file-io.patch (7K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

file-io docstrings

John W. Eaton-6
On  3-Dec-2004, Teemu Ikonen <[hidden email]> wrote:

| I made some cleanups to the documentation strings on functions defined on
| file-io.cc. A patch is attached.

I applied this patch, with a few minor changes.

In most places, if a function only returns one value, the docstrings
have

  @deftypefn {Built-in Function} {} fflush (@var{fid})\n\

instead of

  @deftypefn {Built-in Function} {} @var{status} = fflush (@var{fid})\n\

as in your changes, so I removed the "@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?

jwe


Reply | Threaded
Open this post in threaded view
|

Re: file-io docstrings

Paul Kienzle

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
>
>   @deftypefn {Built-in Function} {} fflush (@var{fid})\n\
>
> instead of
>
>   @deftypefn {Built-in Function} {} @var{status} = fflush
> (@var{fid})\n\
>
> as in your changes, so I removed the "@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