changeset 17416:0bf2fc8562c9

doc: Update documentation for file and directory functions. * libinterp/corefcn/dirfns.cc(Fpwd, Freaddir, Fmkdir, Frmdir, Freadlink, Ffnmatch): Redo docstring. * libinterp/corefcn/dirfns.cc(Fcd): Redo docstring. Return previous working directory if nargout > 0. * libinterp/corefcn/dirfns.cc(Flink, Fsymlink, Frename): Redo docstring. Re-order return values so that highest numbered value is assigned first to avoid re-sizing octave_value_list each time. * libinterp/corefcn/syscalls.cc(Flstat, Fmkfifo, FS_ISREG, FS_ISDIR, FS_ISCHR, FS_ISBLK, FS_ISFIFO, FS_ISLNK, FS_ISSOCK): Redo docstring. * scripts/general/isdir.m: Add more xrefs to @seealso. * scripts/miscellaneous/copyfile.m: Add more xrefs to @seealso. * scripts/miscellaneous/dir.m: Redo docstring. * scripts/miscellaneous/ls.m: Add more xrefs to @seealso.m. * scripts/miscellaneous/movefile.m: Add more xrefs to @seealso.
author Rik <rik@octave.org>
date Mon, 09 Sep 2013 14:30:31 -0700
parents 0b644adf4f31
children 67c6fc2b9f63
files libinterp/corefcn/dirfns.cc libinterp/corefcn/syscalls.cc scripts/general/isdir.m scripts/miscellaneous/copyfile.m scripts/miscellaneous/dir.m scripts/miscellaneous/ls.m scripts/miscellaneous/movefile.m
diffstat 7 files changed, 145 insertions(+), 113 deletions(-) [+]
line wrap: on
line diff
--- a/libinterp/corefcn/dirfns.cc
+++ b/libinterp/corefcn/dirfns.cc
@@ -94,11 +94,16 @@
 
 DEFUN (cd, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn  {Command} {} cd dir\n\
-@deftypefnx {Command} {} chdir dir\n\
-Change the current working directory to @var{dir}.  If @var{dir} is\n\
-omitted, the current directory is changed to the user's home\n\
-directory.  For example,\n\
+@deftypefn  {Command} {} cd @var{dir}\n\
+@deftypefnx {Command} {} cd\n\
+@deftypefnx {Built-in Function} {@var{old_dir} =} cd @var{dir}\n\
+@deftypefnx {Command} {} chdir @dots{}\n\
+Change the current working directory to @var{dir}.\n\
+\n\
+If @var{dir} is omitted, the current directory is changed to the user's home\n\
+directory (@qcode{\"~\"}).\n\
+\n\
+For example,\n\
 \n\
 @example\n\
 cd ~/octave\n\
@@ -108,7 +113,13 @@
 changes the current working directory to @file{~/octave}.  If the\n\
 directory does not exist, an error message is printed and the working\n\
 directory is not changed.\n\
-@seealso{mkdir, rmdir, dir}\n\
+\n\
+@code{chdir} is an alias for @code{cd} and can be used in all of the same\n\
+calling formats.\n\
+\n\
+Compatibility Note: When called with no arguments, @sc{matlab} prints the\n\
+present working directory rather than changing to the user's home directory.\n\
+@seealso{pwd, mkdir, rmdir, dir, ls}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -120,30 +131,22 @@
   if (error_state)
     return retval;
 
+  if (nargout > 0)
+    retval = octave_value (octave_env::get_current_directory ());
+
   if (argc > 1)
     {
       std::string dirname = argv[1];
 
-      if (dirname.length () > 0
-          && ! octave_change_to_directory (dirname))
-        {
-          return retval;
-        }
+      if (dirname.length () > 0)
+        octave_change_to_directory (dirname);
     }
   else
     {
-      // Behave like Unixy shells for "cd" by itself, but be Matlab
-      // compatible if doing "current_dir = cd".
+      std::string home_dir = octave_env::get_home_directory ();
 
-      if (nargout == 0)
-        {
-          std::string home_dir = octave_env::get_home_directory ();
-
-          if (home_dir.empty () || ! octave_change_to_directory (home_dir))
-            return retval;
-        }
-      else
-        retval = octave_value (octave_env::get_current_directory ());
+      if (! home_dir.empty ())
+        octave_change_to_directory (home_dir);
     }
 
   return retval;
@@ -153,9 +156,10 @@
 
 DEFUN (pwd, , ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} pwd ()\n\
+@deftypefn  {Built-in Function} {} pwd ()\n\
+@deftypefnx {Built-in Function} {@var{dir} =} pwd ()\n\
 Return the current working directory.\n\
-@seealso{dir, ls}\n\
+@seealso{cd, dir, ls, mkdir, rmdir}\n\
 @end deftypefn")
 {
   return octave_value (octave_env::get_current_directory ());
@@ -163,14 +167,16 @@
 
 DEFUN (readdir, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir})\n\
-Return names of the files in the directory @var{dir} as a cell array of\n\
-strings.  If an error occurs, return an empty cell array in @var{files}.\n\
+@deftypefn  {Built-in Function} {@var{files} =} readdir (@var{dir})\n\
+@deftypefnx {Built-in Function} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir})\n\
+Return the names of files in the directory @var{dir} as a cell array of\n\
+strings.\n\
 \n\
+If an error occurs, return an empty cell array in @var{files}.\n\
 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{ls, dir, glob}\n\
+@seealso{ls, dir, glob, what}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -207,20 +213,24 @@
   return retval;
 }
 
-// FIXME -- should maybe also allow second arg to specify
-// mode?  OTOH, that might cause trouble with compatibility later...
+// FIXME: should maybe also allow second arg to specify mode?
+//        OTOH, that might cause trouble with compatibility later...
 
 DEFUNX ("mkdir", Fmkdir, args, ,
   "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} mkdir (@var{dir})\n\
-@deftypefnx {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} mkdir (@var{parent}, @var{dir})\n\
+@deftypefn  {Built-in Function} {} mkdir @var{dir}\n\
+@deftypefnx {Built-in Function} {} mkdir (@var{parent}, @var{dir})\n\
+@deftypefnx {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} mkdir (@dots{})\n\
 Create a directory named @var{dir} in the directory @var{parent}.\n\
 \n\
-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{rmdir}\n\
+If no @var{parent} directory is specified the present working directory is\n\
+used.\n\
+\n\
+If successful, @var{status} is 1, and @var{msg}, @var{msgid} are empty\n\
+character strings ("").  Otherwise, @var{status} is 0, @var{msg} contains a\n\
+system-dependent error message, and @var{msgid} contains a unique message\n\
+identifier.\n\
+@seealso{rmdir, pwd, cd}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -295,18 +305,19 @@
 
 DEFUNX ("rmdir", Frmdir, args, ,
   "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@var{dir})\n\
-@deftypefnx {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@var{dir}, \"s\")\n\
+@deftypefn  {Built-in Function} {} rmdir @var{dir}\n\
+@deftypefnx {Built-in Function} {} rmdir (@var{dir}, \"s\")\n\
+@deftypefnx {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@dots{})\n\
 Remove the directory named @var{dir}.\n\
 \n\
-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\
+If successful, @var{status} is 1, and @var{msg}, @var{msgid} are empty\n\
+character strings ("").  Otherwise, @var{status} is 0, @var{msg} contains a\n\
+system-dependent error message, and @var{msgid} contains a unique message\n\
+identifier.\n\
 \n\
 If the optional second parameter is supplied with value @qcode{\"s\"},\n\
 recursively remove all subdirectories as well.\n\
-@seealso{mkdir, confirm_recursive_rmdir}\n\
+@seealso{mkdir, confirm_recursive_rmdir, pwd}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -369,13 +380,14 @@
 
 DEFUNX ("link", Flink, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} link (@var{old}, @var{new})\n\
+@deftypefn  {Built-in Function} {} link @var{old} @var{new}\n\
+@deftypefnx {Built-in Function} {[@var{err}, @var{msg}] =} link (@var{old}, @var{new})\n\
 Create a new link (also known as a hard link) to an existing file.\n\
 \n\
 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{symlink}\n\
+@seealso{symlink, unlink, readlink, lstat}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -401,10 +413,9 @@
 
               int status = octave_link (from, to, msg);
 
-              retval(0) = status;
-
               if (status < 0)
                 retval(1) = msg;
+              retval(0) = status;
             }
         }
     }
@@ -416,13 +427,14 @@
 
 DEFUNX ("symlink", Fsymlink, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} symlink (@var{old}, @var{new})\n\
+@deftypefn  {Built-in Function} {} symlink @var{old} @var{new}\n\
+@deftypefnx {Built-in Function} {[@var{err}, @var{msg}] =} symlink (@var{old}, @var{new})\n\
 Create a symbolic link @var{new} which contains the string @var{old}.\n\
 \n\
 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{link, readlink}\n\
+@seealso{link, unlink, readlink, lstat}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -448,10 +460,9 @@
 
               int status = octave_symlink (from, to, msg);
 
-              retval(0) = status;
-
               if (status < 0)
                 retval(1) = msg;
+              retval(0) = status;
             }
         }
     }
@@ -463,14 +474,15 @@
 
 DEFUNX ("readlink", Freadlink, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{result}, @var{err}, @var{msg}] =} readlink (@var{symlink})\n\
+@deftypefn  {Built-in Function} {} readlink @var{symlink}\n\
+@deftypefnx {Built-in Function} {[@var{result}, @var{err}, @var{msg}] =} readlink (@var{symlink})\n\
 Read the value of the symbolic link @var{symlink}.\n\
 \n\
 If successful, @var{result} contains the contents of the symbolic link\n\
-@var{symlink}, @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{link, symlink}\n\
+@var{symlink}, @var{err} is 0, and @var{msg} is an empty string.\n\
+Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent\n\
+error message.\n\
+@seealso{lstat, symlink, link, unlink, delete}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -506,13 +518,14 @@
 
 DEFUNX ("rename", Frename, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new})\n\
+@deftypefn  {Built-in Function} {} rename @var{old} @var{new}\n\
+@deftypefnx {Built-in Function} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new})\n\
 Change the name of file @var{old} to @var{new}.\n\
 \n\
 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{ls, dir}\n\
+@seealso{movefile, copyfile, ls, dir}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -538,10 +551,9 @@
 
               int status = octave_rename (from, to, msg);
 
-              retval(0) = status;
-
               if (status < 0)
                 retval(1) = msg;
+              retval(0) = status;
             }
         }
     }
@@ -571,9 +583,8 @@
 matches any of the enclosed characters.\n\
 @end table\n\
 \n\
-Tilde expansion\n\
-is performed on each of the patterns before looking for matching file\n\
-names.  For example:\n\
+Tilde expansion is performed on each of the patterns before looking for\n\
+matching file names.  For example:\n\
 \n\
 @example\n\
 ls\n\
@@ -597,7 +608,7 @@
         [2,1] = file2\n\
       @}\n\
 @end example\n\
-@seealso{ls, dir, readdir}\n\
+@seealso{ls, dir, readdir, what, fnmatch}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -656,7 +667,7 @@
 DEFUNX ("fnmatch", Ffnmatch, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} fnmatch (@var{pattern}, @var{string})\n\
-Return 1 or zero for each element of @var{string} that matches any of\n\
+Return true or false for each element of @var{string} that matches any of\n\
 the elements of the string array @var{pattern}, using the rules of\n\
 filename pattern matching.  For example:\n\
 \n\
@@ -666,6 +677,7 @@
      @result{} [ 1; 1; 0 ]\n\
 @end group\n\
 @end example\n\
+@seealso{glob, regexp}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -783,6 +795,7 @@
 When called from inside a function with the @qcode{\"local\"} option, the\n\
 variable is changed locally for the function and any subroutines it calls.  \n\
 The original variable value is restored when exiting the function.\n\
+@seealso{rmdir}\n\
 @end deftypefn")
 {
   return SET_INTERNAL_VARIABLE (confirm_recursive_rmdir);
--- a/libinterp/corefcn/syscalls.cc
+++ b/libinterp/corefcn/syscalls.cc
@@ -749,11 +749,13 @@
 
 DEFUNX ("lstat", Flstat, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{symlink})\n\
+@deftypefn  {Built-in Function} {@var{info} =} lstat (@var{symlink})\n\
+@deftypefnx {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\
+@var{symlink}.\n\
+\n\
+The function outputs are described in the documentation for @code{stat}.\n\
+@seealso{stat, symlink}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -777,12 +779,14 @@
 
 DEFUNX ("mkfifo", Fmkfifo, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkfifo (@var{name}, @var{mode})\n\
-Create a @var{fifo} special file named @var{name} with file mode @var{mode}\n\
+@deftypefn  {Built-in Function} {} mkfifo (@var{name}, @var{mode})\n\
+@deftypefnx {Built-in Function} {[@var{err}, @var{msg}] =} mkfifo (@var{name}, @var{mode})\n\
+Create a FIFO special file named @var{name} with file mode @var{mode}\n\
 \n\
 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{pipe}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -837,6 +841,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{mkfifo}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -975,6 +980,7 @@
   @result{} err = 0\n\
   @result{} msg =\n\
 @end example\n\
+@seealso{lstat, ls, dir}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -1013,8 +1019,9 @@
 DEFUNX ("S_ISREG", FS_ISREG, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} S_ISREG (@var{mode})\n\
-Return true if @var{mode} corresponds to a regular file.  The value\n\
-of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
+Return true if @var{mode} corresponds to a regular file.\n\
+\n\
+The value of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
 @seealso{stat, lstat}\n\
 @end deftypefn")
 {
@@ -1038,8 +1045,9 @@
 DEFUNX ("S_ISDIR", FS_ISDIR, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} S_ISDIR (@var{mode})\n\
-Return true if @var{mode} corresponds to a directory.  The value\n\
-of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
+Return true if @var{mode} corresponds to a directory.\n\
+\n\
+The value of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
 @seealso{stat, lstat}\n\
 @end deftypefn")
 {
@@ -1063,8 +1071,9 @@
 DEFUNX ("S_ISCHR", FS_ISCHR, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} S_ISCHR (@var{mode})\n\
-Return true if @var{mode} corresponds to a character device.  The value\n\
-of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
+Return true if @var{mode} corresponds to a character device.\n\
+\n\
+The value of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
 @seealso{stat, lstat}\n\
 @end deftypefn")
 {
@@ -1088,8 +1097,9 @@
 DEFUNX ("S_ISBLK", FS_ISBLK, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} S_ISBLK (@var{mode})\n\
-Return true if @var{mode} corresponds to a block device.  The value\n\
-of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
+Return true if @var{mode} corresponds to a block device.\n\
+\n\
+The value of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
 @seealso{stat, lstat}\n\
 @end deftypefn")
 {
@@ -1113,8 +1123,9 @@
 DEFUNX ("S_ISFIFO", FS_ISFIFO, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} S_ISFIFO (@var{mode})\n\
-Return true if @var{mode} corresponds to a fifo.  The value\n\
-of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
+Return true if @var{mode} corresponds to a fifo.\n\
+\n\
+The value of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
 @seealso{stat, lstat}\n\
 @end deftypefn")
 {
@@ -1138,8 +1149,9 @@
 DEFUNX ("S_ISLNK", FS_ISLNK, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} S_ISLNK (@var{mode})\n\
-Return true if @var{mode} corresponds to a symbolic link.  The value\n\
-of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
+Return true if @var{mode} corresponds to a symbolic link.\n\
+\n\
+The value of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
 @seealso{stat, lstat}\n\
 @end deftypefn")
 {
@@ -1163,8 +1175,9 @@
 DEFUNX ("S_ISSOCK", FS_ISSOCK, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} S_ISSOCK (@var{mode})\n\
-Return true if @var{mode} corresponds to a socket.  The value\n\
-of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
+Return true if @var{mode} corresponds to a socket.\n\
+\n\
+The value of @var{mode} is assumed to be returned from a call to @code{stat}.\n\
 @seealso{stat, lstat}\n\
 @end deftypefn")
 {
--- a/scripts/general/isdir.m
+++ b/scripts/general/isdir.m
@@ -19,7 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} isdir (@var{f})
 ## Return true if @var{f} is a directory.
-## @seealso{is_absolute_filename, is_rooted_relative_filename}
+## @seealso{exist, stat, is_absolute_filename, is_rooted_relative_filename}
 ## @end deftypefn
 
 function retval = isdir (f)
--- a/scripts/miscellaneous/copyfile.m
+++ b/scripts/miscellaneous/copyfile.m
@@ -31,7 +31,7 @@
 ## system-dependent error message, and @var{msgid} contains a unique message
 ## identifier.  Note that the status code is exacly opposite that of the
 ## @code{system} command.
-## @seealso{movefile, glob}
+## @seealso{movefile, rename, unlink, delete, glob}
 ## @end deftypefn
 
 function [status, msg, msgid] = copyfile (f1, f2, force)
--- a/scripts/miscellaneous/dir.m
+++ b/scripts/miscellaneous/dir.m
@@ -17,40 +17,46 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} dir (@var{directory})
+## @deftypefn  {Function File} {} dir
+## @deftypefnx {Function File} {} dir (@var{directory})
 ## @deftypefnx {Function File} {[@var{list}] =} dir (@var{directory})
-## Display file listing for directory @var{directory}.  If a return
-## value is requested, return a structure array with the fields
+## Display file listing for directory @var{directory}.
+##
+## If @var{directory} is not specified then list the present working directory.
+##
+## If a return value is requested, return a structure array with the fields
 ##
-## @example
-## @group
-## name
-## bytes
-## date
-## isdir
-## statinfo
-## @end group
-## @end example
+## @table @asis
+## @item name
+## File or directory name. 
+## @item date
+## Timestamp of file modification (string value).
+## @item bytes
+## File size in bytes.
+## @item isdir
+## True if name is a directory. 
+## @item datenum
+## Timestamp of file modification as serial date number (double).
+## @item statinfo
+## Information structure returned from @code{stat}.
+## @end table
 ##
-## @noindent
-## where @code{statinfo} is the structure returned from @code{stat}.
-##
-## If @var{directory} is not a directory, return information about the
-## named @var{filename}.  @var{directory} may be a list of directories
-## specified either by name or with wildcard characters (like * and ?)
-## which will be expanded with glob.
+## If @var{directory} is a filename, rather than a directory, then return
+## information about the named file.  @var{directory} may be a list of
+## directories specified either by name or with wildcard characters (like *
+## and ?) which will be expanded with @code{glob}.
 ##
 ## Note that for symbolic links, @code{dir} returns information about
-## the file that the symbolic link points to instead of the link itself.
+## the file that the symbolic link points to rather than the link itself.
 ## However, if the link points to a nonexistent file, @code{dir} returns
 ## information about the link.
-## @seealso{ls, stat, lstat, readdir, glob, filesep}
+## @seealso{ls, readdir, glob, what, stat}
 ## @end deftypefn
 
 ## Author: jwe
 
-## FIXME -- this is quite slow for large directories, so perhaps
-## it should be converted to C++.
+## FIXME: This is quite slow for large directories, so perhaps
+##        it should be converted to C++.
 
 function retval = dir (directory)
 
--- a/scripts/miscellaneous/ls.m
+++ b/scripts/miscellaneous/ls.m
@@ -32,7 +32,7 @@
 ## The @code{dir} and @code{ls} commands are implemented by calling your
 ## system's directory listing command, so the available options may vary
 ## from system to system.
-## @seealso{dir, stat, readdir, glob, filesep, ls_command}
+## @seealso{dir, readdir, glob, what, stat, filesep, ls_command}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/miscellaneous/movefile.m
+++ b/scripts/miscellaneous/movefile.m
@@ -35,7 +35,7 @@
 ## system-dependent error message, and @var{msgid} contains a unique message
 ## identifier.  Note that the status code is exacly opposite that of the
 ## @code{system} command.
-## @seealso{rename, copyfile, glob}
+## @seealso{rename, copyfile, unlink, delete, glob}
 ## @end deftypefn
 
 function [status, msg, msgid] = movefile (f1, f2, force)