# HG changeset patch
# User Rik <rik@octave.org>
# Date 1640707919 28800
# Node ID 1c6e04afe50d9e2e91acdcfa027e94243c361ff0
# Parent  9ed1cf9e446eb79351690083f48d67572b3ca821
doc: improvements to documentation for classes in scripts/ dir.

* +containers/Map.m (remove): Document calling form which returns a Map object.

* @ftp/cd.m: Document calling forms which return CWD.

* @ftp/dir.m: Document calling form which returns struct array.

* @ftp/mput.m: Document calling form which returns cellstr.

* @ftp/rename.m: Use @code{} macro around "ftp" for conformity with other
functions.

* @audioplayer/__get_properties__.m: Match documentation variable names to
function prototype names.

* @audioplayer/set.m: Match function prototype names to documentation.

* @audiorecorder/__get_properties__.m: Match documentation variable names to
function prototype names.

* @audiorecorder/set.m: Match function prototype names to documentation.

diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/+containers/Map.m
--- a/scripts/+containers/Map.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/+containers/Map.m	Tue Dec 28 08:11:59 2021 -0800
@@ -305,6 +305,7 @@
 
       ## -*- texinfo -*-
       ## @deftypefn {} {} Map.remove (@var{keySet})
+      ## @deftypefn {} {@var{newMap) =} Map.remove (@var{keySet})
       ## Remove the list of key/value pairs specified by a cell array of keys
       ## @var{keySet} from the map.
       ##
diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/@ftp/cd.m
--- a/scripts/@ftp/cd.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/@ftp/cd.m	Tue Dec 28 08:11:59 2021 -0800
@@ -24,8 +24,9 @@
 ########################################################################
 
 ## -*- texinfo -*-
-## @deftypefn  {} {} cd (@var{f})
+## @deftypefn  {} {@var{cwd} =} cd (@var{f})
 ## @deftypefnx {} {} cd (@var{f}, @var{path})
+## @deftypefnx {} {@var{new_cwd} =} cd (@var{f}, @var{path})
 ## Get or set the remote directory on the FTP connection @var{f}.
 ##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/@ftp/dir.m
--- a/scripts/@ftp/dir.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/@ftp/dir.m	Tue Dec 28 08:11:59 2021 -0800
@@ -24,10 +24,15 @@
 ########################################################################
 
 ## -*- texinfo -*-
-## @deftypefn {} {@var{lst} =} dir (@var{f})
+## @deftypefn  {} {} dir (@var{f})
+## @deftypefnx {} {@var{lst} =} dir (@var{f})
 ## List the current directory in verbose form for the FTP connection @var{f}.
 ##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
+##
+## If the optional output @var{lst} is requested return a struct array
+## with one entry per file with the fields @code{name}, @code{date},
+## @code{bytes}, @code{isdir}, @code{datenum}.
 ## @end deftypefn
 
 function lst = dir (f)
diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/@ftp/mput.m
--- a/scripts/@ftp/mput.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/@ftp/mput.m	Tue Dec 28 08:11:59 2021 -0800
@@ -24,14 +24,18 @@
 ########################################################################
 
 ## -*- texinfo -*-
-## @deftypefn {} {} mput (@var{f}, @var{file})
+## @deftypefn  {} {} mput (@var{f}, @var{file})
+## @deftypefnx {} {@var{file_list} =} mput (@var{f}, @var{file})
 ## Upload the local file @var{file} into the current remote directory on the
 ## FTP connection @var{f}.
 ##
-## @var{f} is an FTP object returned by the ftp function.
+## @var{f} is an FTP object returned by the @code{ftp} function.
 ##
 ## The argument @var{file} is passed through the @code{glob} function and any
 ## files that match the wildcards in @var{file} will be uploaded.
+##
+## The optional output argument @var{file_list} contains a cell array of
+## strings with the names of the uploaded files.
 ## @end deftypefn
 
 function retval = mput (f, file)
diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/@ftp/rename.m
--- a/scripts/@ftp/rename.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/@ftp/rename.m	Tue Dec 28 08:11:59 2021 -0800
@@ -28,7 +28,7 @@
 ## Rename or move the remote file or directory @var{oldname} to @var{newname},
 ## over the FTP connection @var{f}.
 ##
-## @var{f} is an FTP object returned by the ftp function.
+## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn
 
 function rename (f, oldname, newname)
diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/audio/@audioplayer/__get_properties__.m
--- a/scripts/audio/@audioplayer/__get_properties__.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/audio/@audioplayer/__get_properties__.m	Tue Dec 28 08:11:59 2021 -0800
@@ -24,7 +24,7 @@
 ########################################################################
 
 ## -*- texinfo -*-
-## @deftypefn {} {@var{properties} =} __get_properties__ (@var{player})
+## @deftypefn {} {@var{props} =} __get_properties__ (@var{player})
 ## Return a struct containing all named properties of the audioplayer object
 ## @var{player}.
 ## @end deftypefn
diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/audio/@audioplayer/set.m
--- a/scripts/audio/@audioplayer/set.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/audio/@audioplayer/set.m	Tue Dec 28 08:11:59 2021 -0800
@@ -33,10 +33,10 @@
 ## corresponding value.  Given a structure of @var{properties} with fields
 ## corresponding to property names, set the value of those properties to the
 ## field values.  Given only the audioplayer object, return a structure of
-## settable properties.
+## configurable properties (i.e., writeable properties).
 ## @end deftypefn
 
-function settable = set (varargin)
+function properties = set (varargin)
 
   if (nargin < 1 || nargin > 3)
     print_usage ();
@@ -45,9 +45,9 @@
   player = struct (varargin{1}).player;
 
   if (nargin == 1)
-    settable.SampleRate = {};
-    settable.Tag = {};
-    settable.UserData = {};
+    properties.SampleRate = {};
+    properties.Tag = {};
+    properties.UserData = {};
   elseif (nargin == 2)
     for [value, property] = varargin{2}
       setproperty (player, property, value);
diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/audio/@audiorecorder/__get_properties__.m
--- a/scripts/audio/@audiorecorder/__get_properties__.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/audio/@audiorecorder/__get_properties__.m	Tue Dec 28 08:11:59 2021 -0800
@@ -24,7 +24,7 @@
 ########################################################################
 
 ## -*- texinfo -*-
-## @deftypefn {} {@var{properties} =} __get_properties__ (@var{recorder})
+## @deftypefn {} {@var{props} =} __get_properties__ (@var{recorder})
 ## Return a struct containing all named properties of the recorder object
 ## @var{recorder}.
 ## @end deftypefn
diff -r 9ed1cf9e446e -r 1c6e04afe50d scripts/audio/@audiorecorder/set.m
--- a/scripts/audio/@audiorecorder/set.m	Mon Dec 27 20:04:52 2021 -0800
+++ b/scripts/audio/@audiorecorder/set.m	Tue Dec 28 08:11:59 2021 -0800
@@ -33,10 +33,10 @@
 ## property to a corresponding value.  Given a structure with fields
 ## corresponding to property names, set the value of those properties to the
 ## corresponding field values.  Given only the recorder object, return a
-## structure of settable properties.
+## configurable properties (i.e., writeable properties).
 ## @end deftypefn
 
-function settable = set (varargin)
+function properties = set (varargin)
 
   if (nargin < 1 || nargin > 3)
     print_usage ();
@@ -45,9 +45,9 @@
   recorder = struct (varargin{1}).recorder;
 
   if (nargin == 1)
-    settable.SampleRate = {};
-    settable.Tag = {};
-    settable.UserData = {};
+    properties.SampleRate = {};
+    properties.Tag = {};
+    properties.UserData = {};
   elseif (nargin == 2)
     for [value, property] = varargin{2}
       setproperty (recorder, property, value);