misleading documentation for ferror

[Paul Sundvall]

Hi!
The help for the builtin ferror function claims
"Return 1 if an error condition has been encountered for a given
     file and 0 otherwise"
The implementation however seems to behave just like matlab does.
Also, the second (optional) input parameter is not documented.
I suggest the following help text. See it as a start of discussion:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
[errormessage]           = ferror(fid)
[errormessage,errorcode] = ferror(fid)
                      ...= ferror(fid,command)

Checks if the last operation on file given by file handle fid resulted
in error. If there was no error, errormessage will be empty and
errorcode set to 0. If there was an error, errormessage is set
appropriately and errorcode is nonzero.
??what about command??
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Also, the output is not assigned on invalid input such as an invalid fid
or bad argument count. Instead of users having to wrap their calls to
ferror in try/catch, it would be better to set the output appropriately.

I use debian 3.0.1 packaged by debian(lenny), but the report is valid
for the octave repository as well (checked today).

Thanks,
Paul Sundvall
_______________________________________________
Bug-octave mailing list
Bug-octave@...
https://www-old.cae.wisc.edu/mailman/listinfo/bug-octave

[John W. Eaton-3]

On  6-Nov-2009, Paul Sundvall wrote:

| The help for the builtin ferror function claims
| "Return 1 if an error condition has been encountered for a given
|      file and 0 otherwise"
| The implementation however seems to behave just like matlab does.
| Also, the second (optional) input parameter is not documented.
| I suggest the following help text. See it as a start of discussion:
|
| %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
| [errormessage]           = ferror(fid)
| [errormessage,errorcode] = ferror(fid)
|                       ...= ferror(fid,command)
|
| Checks if the last operation on file given by file handle fid resulted
| in error. If there was no error, errormessage will be empty and
| errorcode set to 0. If there was an error, errormessage is set
| appropriately and errorcode is nonzero.
| ??what about command??
| %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
| Also, the output is not assigned on invalid input such as an invalid fid
| or bad argument count. Instead of users having to wrap their calls to
| ferror in try/catch, it would be better to set the output appropriately.
|
| I use debian 3.0.1 packaged by debian(lenny), but the report is valid
| for the octave repository as well (checked today).

The doc string is now:

 -- Built-in Function: [ERR, MSG] = ferror (FID, "clear")
     Return 1 if an error condition has been encountered for the file ID
     FID and 0 otherwise.  Note that it will only return 1 if an error
     has already been encountered, not if the next operation will
     result in an error condition.

     The second argument is optional.  If it is supplied, also clear the
     error condition.

Thanks,

jwe
_______________________________________________
Bug-octave mailing list
Bug-octave@...
https://www-old.cae.wisc.edu/mailman/listinfo/bug-octave