diff libinterp/octave-value/ov-struct.cc @ 18533:ea0d4dea1a17 stable

doc: Update documentation for functions in octave-value dir. * ov-bool-mat.cc (Flogical): Document that input must be numeric. Document incompatibility with Matlab regarding complex inputs. * ov-cell.cc (Fcell): Add seealso references. * ov-cell.cc (Fcellstr): Document that trailing spaces are trimmed. Add seealso references. * ov-cell.cc (Fstruct2cell): Use lowercase names in @var references. * ov-class.cc (Fismethod): Add seealso reference to isprop. * ov-class.cc (Fsuperiorto): Add seealso reference to inferiorto. * ov-class.cc (Finferiorto): Add seealso reference to superiorto. * ov-fcn-handle.cc (Ffunctions): Add table to documentation describing return values. * ov-fcn-handle.cc (Ffunc2str): Add seealso links to str2func, functions. * ov-fcn-handle.cc (Fstr2func): Add seealso links to func2str, inline. * ov-fcn-handle.cc (Fis_function_handle): Add seealso links to functions. * ov-fcn-inline.cc (Finline): Add note that the use of inline is discouraged. Add seealso link to str2func. * ov-int16.cc (Fint16): Add seealso links to docstring. * ov-int32.cc (Fint32): Add seealso links to docstring. * ov-int64.cc (Fint64): Add seealso links to docstring. * ov-int8.cc (Fint8): Add seealso links to docstring. * ov-oncleanup.cc (FonCleanup): clarify docstring by using "function" rather than "action" for what gets called when onCleanup object is destroyed. * ov-struct.cc (Fstruct): Add additional calling forms. Add seealso links. * ov-struct.cc (Fisfield): Add additional calling forms. Add seealso link. * ov-struct.cc (Fnfields): Add seealso link. * ov-struct.cc (Fcell2struct): Add additional calling forms. Add seealso link. * ov-struct.cc (Frmfield): Emphasize that a copy of the struct is returned. Add seealso link. * ov-struct.cc (Fstruct_levels_to_print): Add seealso link to print_struct_array_contents. * ov-struct.cc (Fprint_struct_array_contents): Add seealso link to struct_levels_to_print. * ov-typeinfo.cc (Ftypeinfo): Add seealso links to class, isa. * ov-uint16.cc (Fuint16): Add seealso links to docstring. * ov-uint32.cc (Fuint32): Add seealso links to docstring. * ov-uint64.cc (Fuint64): Add seealso links to docstring. * ov-uint8.cc (Fuint8): Add seealso links to docstring. * ov-usr-fcn.cc (Fnargin): Add example based on 'union' function. * ov-usr-fcn.cc (Fnargout): Add example based on 'imread' function. * ov-usr-fcn.cc (Foptimize_subsasgn_calls): Improve docstring. * ov.cc (Fsubsref): Rephrase one sentence. * fieldnames.m: Add more functions to seealso links. * getfield.m: Re-order seealso links. * setfield.m: Re-order seealso links. * isprop.m Add ismethod, isobject to seealso links.
author Rik <rik@octave.org>
date Sat, 01 Mar 2014 21:50:13 -0800
parents bd9d34f28b0f
children f958e8cd6348
line wrap: on
line diff
--- a/libinterp/octave-value/ov-struct.cc	Fri Feb 28 16:55:26 2014 -0800
+++ b/libinterp/octave-value/ov-struct.cc	Sat Mar 01 21:50:13 2014 -0800
@@ -1763,12 +1763,14 @@
 
 DEFUN (struct, args, ,
        "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} struct (@var{field1}, @var{value1}, @var{field2}, @var{value2}, @dots{})\n\
+@deftypefn  {Built-in Function} {@var{s} =} struct ()\n\
+@deftypefnx {Built-in Function} {@var{s} =} struct (@var{field1}, @var{value1}, @var{field2}, @var{value2}, @dots{})\n\
+@deftypefnx {Built-in Function} {@var{s} =} struct (@var{obj})\n\
 \n\
 Create a scalar or array structure and initialize its values.  The\n\
-@var{field1}, @var{field2}, @dots{} variables are strings giving the\n\
+@var{field1}, @var{field2}, @dots{} variables are strings specifying the\n\
 names of the fields and the @var{value1}, @var{value2}, @dots{}\n\
-variables can be any type.\n\
+variables can be of any type.\n\
 \n\
 If the values are cell arrays, create a structure array and initialize\n\
 its values.  The dimensions of each cell array of values must match.\n\
@@ -1803,7 +1805,7 @@
 @end example\n\
 \n\
 @noindent\n\
-The first case is an ordinary scalar struct, one field, one value.  The\n\
+The first case is an ordinary scalar struct---one field, one value.  The\n\
 second produces an empty struct array with one field and no values, since\n\
 s being passed an empty cell array of struct array values.  When the value is\n\
 a cell array containing a single entry, this becomes a scalar struct with\n\
@@ -1812,6 +1814,7 @@
 \n\
 Finally, if the value is a non-scalar cell array, then @code{struct}\n\
 produces a struct @strong{array}.\n\
+@seealso{cell2struct, fieldnames, orderfields, getfield, setfield, rmfield, structfun}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -2006,10 +2009,12 @@
 
 DEFUN (isfield, args, ,
        "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} isfield (@var{x}, @var{name})\n\
-Return true if the @var{x} is a structure and it\n\
-includes an element named @var{name}.  If @var{name} is a cell\n\
-array of strings then a logical array of equal dimension is returned.\n\
+@deftypefn  {Built-in Function} {} isfield (@var{x}, \"@var{name}\")\n\
+@deftypefnx {Built-in Function} {} isfield (@var{x}, @var{name})\n\
+Return true if the @var{x} is a structure and it includes an element named\n\
+@var{name}.  If @var{name} is a cell array of strings then a logical array of\n\
+equal dimension is returned.\n\
+@seealso{fieldnames}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -2065,6 +2070,7 @@
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} nfields (@var{s})\n\
 Return the number of fields of the structure @var{s}.\n\
+@seealso{fieldnames}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -2095,7 +2101,8 @@
 
 DEFUN (cell2struct, args, ,
        "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} cell2struct (@var{cell}, @var{fields}, @var{dim})\n\
+@deftypefn  {Built-in Function} {} cell2struct (@var{cell}, @var{fields})\n\
+@deftypefnx {Built-in Function} {} cell2struct (@var{cell}, @var{fields}, @var{dim})\n\
 Convert @var{cell} to a structure.  The number of fields in @var{fields}\n\
 must match the number of elements in @var{cell} along dimension @var{dim},\n\
 that is @code{numel (@var{fields}) == size (@var{cell}, @var{dim})}.\n\
@@ -2115,6 +2122,7 @@
 \n\
 @end group\n\
 @end example\n\
+@seealso{struct2cell, cell2mat, struct}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -2231,10 +2239,10 @@
        "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {@var{s} =} rmfield (@var{s}, \"@var{f}\")\n\
 @deftypefnx {Built-in Function} {@var{s} =} rmfield (@var{s}, @var{f})\n\
-Return a copy of the structure (array) @var{s} with the field @var{f}\n\
+Return a @emph{copy} of the structure (array) @var{s} with the field @var{f}\n\
 removed.  If @var{f} is a cell array of strings or a character array, remove\n\
 each of the named fields.\n\
-@seealso{cellstr, iscellstr, setfield}\n\
+@seealso{orderfields, fieldnames}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -2302,6 +2310,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{print_struct_array_contents}\n\
 @end deftypefn")
 {
   return SET_INTERNAL_VARIABLE_WITH_LIMITS (struct_levels_to_print, -1,
@@ -2314,14 +2323,17 @@
 @deftypefnx {Built-in Function} {@var{old_val} =} print_struct_array_contents (@var{new_val})\n\
 @deftypefnx {Built-in Function} {} print_struct_array_contents (@var{new_val}, \"local\")\n\
 Query or set the internal variable that specifies whether to print struct\n\
-array contents.  If true, values of struct array elements are printed.\n\
-This variable does not affect scalar structures.  Their elements\n\
-are always printed.  In both cases, however, printing will be limited to\n\
+array contents.\n\
+\n\
+If true, values of struct array elements are printed.\n\
+This variable does not affect scalar structures whose elements are always\n\
+printed.  In both cases, however, printing will be limited to\n\
 the number of levels specified by @var{struct_levels_to_print}.\n\
 \n\
 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{struct_levels_to_print}\n\
 @end deftypefn")
 {
   return SET_INTERNAL_VARIABLE (print_struct_array_contents);