changeset 12291:b6840c49fbdb release-3-4-x

Add S_ISBLK and family of functions to documentation. Improve docstrings for functions in System Utilities::File Utilities.
author Rik <octave@nomad.inbox5.com>
date Sat, 29 Jan 2011 21:28:38 -0800
parents 75a496c7a3df
children 76617b82cf4c
files doc/ChangeLog doc/interpreter/system.txi scripts/ChangeLog scripts/miscellaneous/copyfile.m scripts/miscellaneous/movefile.m scripts/miscellaneous/tempname.m src/ChangeLog src/dirfns.cc src/file-io.cc src/input.cc src/syscalls.cc
diffstat 11 files changed, 94 insertions(+), 55 deletions(-) [+]
line wrap: on
line diff
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2011-01-29  Rik  <octave@nomad.inbox5.com>
+
+	* interpreter/system.txi: Add S_ISBLK and related functions to
+	documentation.
+
 2011-01-29  Rik  <octave@nomad.inbox5.com>
 
 	* interpreter/optim.txi: Add glpkmex function to documentation.
--- a/doc/interpreter/system.txi
+++ b/doc/interpreter/system.txi
@@ -149,22 +149,23 @@
 @node Filesystem Utilities
 @section Filesystem Utilities
 
-Octave includes the following functions for renaming and deleting files,
-creating, deleting, and reading directories, and for getting information
-about the status of files.
+Octave includes many utility functions for copying, moving, renaming, and deleting files; for creating, reading, and deleting directories; for retrieving
+status information on files; and for manipulating file and path names.
+
+@DOCSTRING(movefile)
 
 @DOCSTRING(rename)
 
+@DOCSTRING(copyfile)
+
+@DOCSTRING(unlink)
+
 @DOCSTRING(link)
 
 @DOCSTRING(symlink)
 
 @DOCSTRING(readlink)
 
-@DOCSTRING(unlink)
-
-@DOCSTRING(readdir)
-
 @DOCSTRING(mkdir)
 
 @DOCSTRING(rmdir)
@@ -178,43 +179,53 @@
 @anchor{doc-lstat}
 @DOCSTRING(stat)
 
+@DOCSTRING(S_ISBLK)
+
+@DOCSTRING(S_ISCHR)
+
+@DOCSTRING(S_ISDIR)
+
+@DOCSTRING(S_ISFIFO)
+
+@DOCSTRING(S_ISLNK)
+
+@DOCSTRING(S_ISREG)
+
 @DOCSTRING(fileattrib)
 
 @DOCSTRING(isdir)
 
+@DOCSTRING(readdir)
+
 @DOCSTRING(glob)
 
 @DOCSTRING(fnmatch)
 
 @DOCSTRING(file_in_path)
 
+@DOCSTRING(filesep)
+
+@DOCSTRING(filemarker)
+
+@DOCSTRING(fileparts)
+
+@DOCSTRING(fullfile)
+
 @DOCSTRING(tilde_expand)
 
 @DOCSTRING(canonicalize_file_name)
 
-@DOCSTRING(movefile)
-
-@DOCSTRING(copyfile)
-
-@DOCSTRING(fileparts)
-
-@DOCSTRING(filesep)
-
-@DOCSTRING(filemarker)
-
-@DOCSTRING(fullfile)
-
-@DOCSTRING(tempdir)
-
-@DOCSTRING(tempname)
-
-@DOCSTRING(P_tmpdir)
+@DOCSTRING(make_absolute_filename)
 
 @DOCSTRING(is_absolute_filename)
 
 @DOCSTRING(is_rooted_relative_filename)
 
-@DOCSTRING(make_absolute_filename)
+@DOCSTRING(P_tmpdir)
+
+@DOCSTRING(tempdir)
+
+@DOCSTRING(tempname)
 
 @node File Archiving Utilities
 @section File Archiving Utilities
--- a/scripts/ChangeLog
+++ b/scripts/ChangeLog
@@ -1,3 +1,8 @@
+2010-01-29  Rik  <octave@nomad.inbox5.com>
+
+	* miscellaneous/copyfile.m, miscellaneous/movefile.m,
+	miscellaneous/tempname.m: Improve docstrings
+
 2010-01-29  Rik  <octave@nomad.inbox5.com>
 
 	* deprecated/module.mk, image/module.mk: Deprecate saveimage.m.
--- a/scripts/miscellaneous/copyfile.m
+++ b/scripts/miscellaneous/copyfile.m
@@ -17,17 +17,18 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} copyfile (@var{f1}, @var{f2}, @var{force})
+## @deftypefn  {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} copyfile (@var{f1}, @var{f2})
+## @deftypefnx {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} copyfile (@var{f1}, @var{f2}, 'f')
 ## Copy the file @var{f1} to the new name @var{f2}.  The name @var{f1}
 ## may contain globbing patterns.  If @var{f1} expands to multiple file
-## names, @var{f2} must be a directory.  If @var{force} is given and equals
-## the string "f" the copy operation will be forced.
+## names, @var{f2} must be a directory.  If the force flag 'f' is given then
+## existing destination files will be overwritten without prompting.
 ##
-## If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty\n\
-## character strings.  Otherwise, @var{status} is 0, @var{msg} contains a\n\
-## system-dependent error message, and @var{msgid} contains a unique\n\
-## message identifier.\n\
-## @seealso{glob, movefile}
+## If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty
+## character strings.  Otherwise, @var{status} is 0, @var{msg} contains a
+## system-dependent error message, and @var{msgid} contains a unique
+## message identifier.
+## @seealso{movefile}
 ## @end deftypefn
 
 function [status, msg, msgid] = copyfile (f1, f2, force)
--- a/scripts/miscellaneous/movefile.m
+++ b/scripts/miscellaneous/movefile.m
@@ -17,16 +17,18 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@var{f1}, @var{f2})
+## @deftypefn  {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@var{f1}, @var{f2})
+## @deftypefnx {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@var{f1}, @var{f2}, 'f')
 ## Move the file @var{f1} to the new name @var{f2}.  The name @var{f1}
 ## may contain globbing patterns.  If @var{f1} expands to multiple file
-## names, @var{f2} must be a directory.
+## names, @var{f2} must be a directory.  If the force flag 'f' is given
+## then any existing files will be overwritten without prompting.
 ##
-## If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty\n\
-## character strings.  Otherwise, @var{status} is 0, @var{msg} contains a\n\
-## system-dependent error message, and @var{msgid} contains a unique\n\
-## message identifier.\n\
-## @seealso{glob}
+## If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty
+## character strings.  Otherwise, @var{status} is 0, @var{msg} contains a
+## system-dependent error message, and @var{msgid} contains a unique
+## message identifier.
+## @seealso{rename, copyfile}
 ## @end deftypefn
 
 function [status, msg, msgid] = movefile (f1, f2, force)
--- a/scripts/miscellaneous/tempname.m
+++ b/scripts/miscellaneous/tempname.m
@@ -17,8 +17,11 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {filename =} tempname ()
+## @deftypefn  {Function File} {} tempname ()
+## @deftypefnx {Function File} {} tempname (@var{dir})
+## @deftypefnx {Function File} {} tempname (@var{dir}, @var{prefix})
 ## This function is an alias for @code{tmpnam}.
+## @seealso{tmpnam}
 ## @end deftypefn
 
 function filename = tempname (varargin)
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,10 @@
+2011-01-29  Rik  <octave@nomad.inbox5.com>
+
+	* dirfns.cc (readdir, filesep, pathsep): Improve docstrings
+	* file-io.cc (tmpnam): Improve docstring
+	* input.cc (filemarker): Improve docstring
+	* syscalls.cc (stat, lstat): Improve docstring
+
 2011-01-29  Rik  <octave@nomad.inbox5.com>
 
 	* DLD-FUNCTIONS/getrusage.cc, toplev.cc: Improve docstring
--- a/src/dirfns.cc
+++ b/src/dirfns.cc
@@ -157,7 +157,7 @@
 If successful, @var{err} is 0 and @var{msg} is an empty string.\n\
 Otherwise, @var{err} is nonzero and @var{msg} contains a\n\
 system-dependent error message.\n\
-@seealso{dir, glob}\n\
+@seealso{ls, dir, glob}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -584,7 +584,7 @@
           [2,1] = file2\n\
         @}\n\
 @end example\n\
-@seealso{dir, ls, stat, readdir, regexp}\n\
+@seealso{ls, dir, readdir}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -684,11 +684,11 @@
 @deftypefnx {Built-in Function} {} filesep ('all')\n\
 Return the system-dependent character used to separate directory names.\n\
 \n\
-If 'all' is given, the function return all valid file separators in\n\
+If 'all' is given, the function returns all valid file separators in\n\
 the form of a string.  The list of file separators is system-dependent.\n\
-It is / (forward slash) under UNIX or Mac OS X, / and \\ (forward and\n\
-backward slashes) under Windows.\n\
-@seealso{pathsep, dir, ls}\n\
+It is @samp{/} (forward slash) under UNIX or Mac OS X, @samp{/} and @samp{\\}\n\
+(forward and backward slashes) under Windows.\n\
+@seealso{pathsep}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -719,9 +719,8 @@
     "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {@var{val} =} pathsep ()\n\
 @deftypefnx {Built-in Function} {@var{old_val} =} pathsep (@var{new_val})\n\
-Query or set the character used to separate directories in\n\
-a path.\n\
-@seealso{filesep, dir, ls}\n\
+Query or set the character used to separate directories in a path.\n\
+@seealso{filesep}\n\
 @end deftypefn")
 {
   octave_value retval;
--- a/src/file-io.cc
+++ b/src/file-io.cc
@@ -1853,7 +1853,9 @@
 
 DEFUNX ("tmpnam", Ftmpnam, args, ,
  "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} tmpnam (@var{dir}, @var{prefix})\n\
+@deftypefn  {Built-in Function} {} tmpnam ()\n\
+@deftypefnx {Built-in Function} {} tmpnam (@var{dir})\n\
+@deftypefnx {Built-in Function} {} tmpnam (@var{dir}, @var{prefix})\n\
 Return a unique temporary file name as a string.\n\
 \n\
 If @var{prefix} is omitted, a value of @code{\"oct-\"} is used.\n\
--- a/src/input.cc
+++ b/src/input.cc
@@ -1506,7 +1506,8 @@
 
 DEFUN (filemarker, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} filemarker ()\n\
+@deftypefn  {Built-in Function} {@var{val} =} filemarker ()\n\
+@deftypefnx {Built-in Function} {} filemarker (@var{new_val})\n\
 Query or set the character used to separate filename from the\n\
 the subfunction names contained within the file.  This can be used in\n\
 a generic manner to interact with subfunctions.  For example,\n\
--- a/src/syscalls.cc
+++ b/src/syscalls.cc
@@ -743,8 +743,11 @@
 
 DEFUNX ("lstat", Flstat, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file})\n\
-See stat.\n\
+@deftypefn {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{symlink})\n\
+Return a structure @var{info} containing information about the symbolic link\n\
+@var{symlink}.  The function outputs are described in the documentation for\n\
+@code{stat}.\n\
+@seealso{stat}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -880,7 +883,7 @@
 @deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{fid})\n\
 @deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file})\n\
 @deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{fid})\n\
-Return a structure @var{s} containing the following information about\n\
+Return a structure @var{info} containing the following information about\n\
 @var{file} or file identifier @var{fid}.\n\
 \n\
 @table @code\n\