From maintainers-request at octave dot org Fri Dec 3 07:28:35 2004 Subject: file-io docstrings From: Teemu Ikonen To: maintainers at octave dot org Date: Fri, 3 Dec 2004 15:22:36 +0200 --yrj/dFKFPuw6o+aM Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Hi, I made some cleanups to the documentation strings on functions defined on file-io.cc. A patch is attached. Teemu --yrj/dFKFPuw6o+aM Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="file-io.patch" --- file-io.cc.orig 2004-12-03 14:14:38.000000000 +0200 +++ file-io.cc 2004-12-03 15:16:14.000000000 +0200 at @ -182,7 +182,8 @@ at deftypefn {Built-in Function} {} fclose (@var{fid})\n\ Closes the specified file. If successful, at code{fclose} returns 0,\n\ otherwise, it returns -1.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fopen, fseek, ftell}") { octave_value retval = -1; at @ -198,12 +199,16 @@ DEFUN (fflush, args, , "-*- texinfo -*-\n\ - at deftypefn {Built-in Function} {} fflush (@var{fid})\n\ + at deftypefn {Built-in Function} {} @var{status} = fflush (@var{fid})\n\ Flush output to at var{fid} dot This is useful for ensuring that all\n\ pending output makes it to the screen before some other event occurs.\n\ For example, it is always a good idea to flush the standard output\n\ stream before calling at code{input} dot \n\ - at end deftypefn") +\n\ + at code{fflush} returns 0 on success and an OS dependent error value\n\ +( at minus{}1 on unix) on error.\n\ + at end deftypefn\n\ + at seealso{fopen, fclose}") { octave_value retval = -1; at @ -246,7 +251,8 @@ character.\n\ \n\ If there are no more characters to read, at code{fgetl} returns @minus{}1.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fread, fscanf}") { static std::string who = "fgetl"; at @ -294,7 +300,8 @@ character.\n\ \n\ If there are no more characters to read, at code{fgets} returns @minus{}1.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fread, fscanf}") { static std::string who = "fgets"; at @ -490,7 +497,8 @@ at noindent\n\ however, conversions are currently only supported for at samp{native}\n\ at samp{ieee-be}, and @samp{ieee-le} formats.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fclose, fread, fseek}") { octave_value_list retval; at @ -625,15 +633,19 @@ DEFUN (fseek, args, , "-*- texinfo -*-\n\ - at deftypefn {Built-in Function} {} fseek (@var{fid}, @var{offset}, @var{origin})\n\ -Set the file pointer to any location within the file at var{fid} dot The\n\ -pointer is positioned at var{offset} characters from the @var{origin},\n\ + at deftypefn {Built-in Function} {} @var{status} = fseek (@var{fid}, @var{offset}, @var{origin})\n\ +Set the file pointer to any location within the file at var{fid} dot \n\ +\n\ +The pointer is positioned at var{offset} characters from the @var{origin},\n\ which may be one of the predefined variables at code{SEEK_CUR} (current\n\ position), at code{SEEK_SET} (beginning), or @code{SEEK_END} (end of\n\ -file). If at var{origin} is omitted, @code{SEEK_SET} is assumed. The\n\ -offset must be zero, or a value returned by at code{ftell} (in which case\n\ - at var{origin} must be @code{SEEK_SET}.\n\ - at end deftypefn") +file) or strings \"cof\", \"bof\" or \"eof\". If at var{origin} is omitted,\n\ + at code{SEEK_SET} is assumed. The offset must be zero, or a value returned\n\ +by at code{ftell} (in which case @var{origin} must be @code{SEEK_SET}.\n\ +\n\ +Return value at var{status} is 0 on success and -1 on error.\n\ + at end deftypefn\n\ + at seealso{ftell, fopen, fclose}") { octave_value retval = -1; at @ -662,7 +674,8 @@ at deftypefn {Built-in Function} {} ftell (@var{fid})\n\ Return the position of the file pointer as the number of characters\n\ from the beginning of the file at var{fid} dot \n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fseek, fopen, fclose}") { octave_value retval = -1; at @ -686,7 +699,8 @@ at deftypefn {Built-in Function} {} fprintf (@var{fid}, @var{template}, @dots{})\n\ This function is just like at code{printf}, except that the output is\n\ written to the stream at var{fid} instead of @code{stdout}.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{printf, sprintf, fread, fscanf, fopen, fclose}") { static std::string who = "fprintf"; at @ -744,11 +758,13 @@ DEFUN (printf, args, nargout, "-*- texinfo -*-\n\ - at deftypefn {Built-in Function} {} printf (@var{fid}, @var{template}, @dots{})\n\ + at deftypefn {Built-in Function} {} @var{count} = printf (@var{template}, @dots{})\n\ Print optional arguments under the control of the template string\n\ at var{template} to the stream @code{stdout}.\n\ +\n\ +Returns the number of characters printed.\n\ at end deftypefn\n\ - at seealso{fprintf and sprintf}") + at seealso{fprintf, sprintf, scanf}") { static std::string who = "printf"; at @ -790,8 +806,10 @@ DEFUN (fputs, args, , "-*- texinfo -*-\n\ - at deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string})\n\ + at deftypefn {Built-in Function} {} @var{status} = fputs (@var{fid}, @var{string})\n\ Write a string to a file with no formatting.\n\ +\n\ +Returns a non-negative number on success and EOF on error.\n\ at end deftypefn") { static std::string who = "fputs"; at @ -817,6 +835,8 @@ "-*- texinfo -*-\n\ at deftypefn {Built-in Function} {} puts (@var{string})\n\ Write a string to the standard output with no formatting.\n\ +\n\ +Returns a non-negative number on success and EOF on error.\n\ at end deftypefn") { static std::string who = "puts"; at @ -839,7 +859,8 @@ suitably sized string as an argument, Octave's at code{sprintf} function\n\ returns the string, automatically sized to hold all of the items\n\ converted.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{printf, fprintf, sscanf}") { static std::string who = "sprintf"; at @ -930,7 +951,8 @@ single scalar return value. This form is more `C-like', and also\n\ compatible with previous versions of Octave. The number of successful\n\ conversions is returned in at var{count}\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{scanf, sscanf, fread, fprintf}") { static std::string who = "fscanf"; at @ -1001,7 +1023,8 @@ This is like at code{fscanf}, except that the characters are taken from the\n\ string at var{string} instead of from a stream. Reaching the end of the\n\ string is treated as an end-of-file condition.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fscanf, scanf, sprintf}") { static std::string who = "sscanf"; at @ -1099,7 +1122,8 @@ \n\ It is currently not useful to call at code{scanf} in interactive\n\ programs.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fscanf, sscanf, printf}") { int nargin = args.length (); at @ -1342,7 +1366,8 @@ \n\ The data read from the file is returned in at var{val}, and the number of\n\ values read is returned in at code{count}\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fwrite, fopen, fclose}") { octave_value_list retval; at @ -1453,7 +1478,8 @@ \n\ The behavior of at code{fwrite} is undefined if the values in @var{data}\n\ are too large to fit in the specified precision.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fread, fopen, fclose}") { octave_value retval = -1; at @ -1494,7 +1520,8 @@ file and 0 otherwise. Note that it will only return 1 if the end of the\n\ file has already been encountered, not if the next read operation will\n\ result in an end-of-file condition.\n\ - at end deftypefn") + at end deftypefn\n\ + at seealso{fread, fopen, fclose}") { octave_value retval = -1; at @ -1928,7 +1955,7 @@ "-*- texinfo -*-\n\ at defvr {Built-in Variable} P_tmpdir\n\ The default name of the directory for temporary files on this system.\n\ -of this variable is system dependent.\n\ +The value of this variable is system dependent.\n\ at end defvr"); // NOTE: the values of SEEK_SET, SEEK_CUR, and SEEK_END have to be --yrj/dFKFPuw6o+aM--