changeset 27973:8a07553faf2b

doc: Overhaul section about function argument validation (bug #57627). * doc/interpreter/func.txi: Create new subsection "Validating Arguments" and move description of most existing argument validation methods there in three further subsubsections. New description for the "mustBe*" validator functions. * scripts/miscellaneous/mustBeNonzero.m: Remove unnecessary curly braket.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Wed, 22 Jan 2020 01:20:33 +0900
parents 8f33435cfb00
children c014440a2935
files doc/interpreter/func.txi scripts/miscellaneous/mustBeNonzero.m
diffstat 2 files changed, 109 insertions(+), 39 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/func.txi	Wed Jan 22 00:26:59 2020 +0900
+++ b/doc/interpreter/func.txi	Wed Jan 22 01:20:33 2020 +0900
@@ -37,6 +37,7 @@
 * Variable-length Argument Lists::
 * Ignoring Arguments::
 * Default Arguments::
+* Validating Arguments::
 * Function Files::
 * Script Files::
 * Function Handles Anonymous Functions Inline Functions::
@@ -426,49 +427,13 @@
 
 @DOCSTRING(nargout)
 
-It is good practice at the head of a function to verify that it has been called
-correctly.  In Octave the following idiom is seen frequently
-
-@example
-@group
-if (nargin < min_#_inputs || nargin > max_#_inputs)
-  print_usage ();
-endif
-@end group
-@end example
-
-@noindent
-which stops the function execution and prints a message about the correct
-way to call the function whenever the number of inputs is wrong.
-
-For compatibility with @sc{matlab}, @code{narginchk} and @code{nargoutchk} are
-available which provide similar error checking.
-
-@DOCSTRING(narginchk)
-
-@DOCSTRING(nargoutchk)
-
-Besides the number of arguments, inputs can be checked for various properties.
-@code{validatestring} is used for string arguments and
-@code{validateattributes} for numeric arguments.
-
-@DOCSTRING(validatestring)
-
-@DOCSTRING(validateattributes)
-
-If none of the preceding functions is sufficient there is also the class
-@code{inputParser} which can perform extremely complex input checking for
-functions.
-
-@DOCSTRING(inputParser)
-
-@anchor{XREFvarargin} @anchor{XREFvarargout}
-
 @node Variable-length Return Lists
 @section Variable-length Return Lists
 @cindex variable-length return lists
 @cindex @code{varargout}
 
+@anchor{XREFvarargout}
+
 It is possible to return a variable number of output arguments from a
 function using a syntax that's similar to the one used with the
 special @code{varargin} parameter name.  To let a function return a
@@ -512,6 +477,8 @@
 @cindex variable-length argument lists
 @cindex @code{varargin}
 
+@anchor{XREFvarargin}
+
 Sometimes the number of input arguments is not known when the function
 is defined.  As an example think of a function that returns the smallest
 of all its input arguments.  For example:
@@ -677,6 +644,7 @@
 @end example
 
 @DOCSTRING(isargout)
+
 @node Default Arguments
 @section Default Arguments
 @cindex default arguments
@@ -740,6 +708,108 @@
 @end group
 @end example
 
+@node Validating Arguments
+@section Validating Arguments
+@cindex validating arguments
+
+Octave is a weakly typed programming language.  Thus it is possible to
+call a function with arguments, that probably cause errors or might have
+undesirable side effects.  For example calling a string processing function
+with a huge sparse matrix.
+
+It is good practice at the head of a function to verify that it has been
+called correctly.  Octave offers several functions for this purpose.
+
+@menu
+* Validating the number of Arguments::
+* Validating the type of Arguments::
+* Parsing Arguments::
+@end menu
+
+@node Validating the number of Arguments
+@subsection Validating the number of Arguments
+
+In Octave the following idiom is seen frequently at the beginning of a
+function definition:
+
+@example
+@group
+if (nargin < min_#_inputs || nargin > max_#_inputs)
+  print_usage ();
+endif
+@end group
+@end example
+
+@noindent
+which stops the function execution and prints a message about the correct
+way to call the function whenever the number of inputs is wrong.
+
+Similar error checking is provided by @code{narginchk} and
+@code{nargoutchk}.
+
+@DOCSTRING(narginchk)
+
+@DOCSTRING(nargoutchk)
+
+@node Validating the type of Arguments
+@subsection Validating the type of Arguments
+
+Besides the number of arguments, inputs can be checked for various
+properties.  @code{validatestring} is used for string arguments and
+@code{validateattributes} for numeric arguments.
+
+@DOCSTRING(validatestring)
+
+@DOCSTRING(validateattributes)
+
+As alternative to @code{validateattributes} there are several shorter
+convenience functions to check for individual properties.
+
+@DOCSTRING(mustBeFinite)
+
+@DOCSTRING(mustBeGreaterThan)
+
+@DOCSTRING(mustBeGreaterThanOrEqual)
+
+@DOCSTRING(mustBeInteger)
+
+@DOCSTRING(mustBeLessThan)
+
+@DOCSTRING(mustBeLessThanOrEqual)
+
+@DOCSTRING(mustBeMember)
+
+@DOCSTRING(mustBeNegative)
+
+@DOCSTRING(mustBeNonempty)
+
+@DOCSTRING(mustBeNonNan)
+
+@DOCSTRING(mustBeNonnegative)
+
+@DOCSTRING(mustBeNonpositive)
+
+@DOCSTRING(mustBeNonsparse)
+
+@DOCSTRING(mustBeNonzero)
+
+@DOCSTRING(mustBeNumeric)
+
+@DOCSTRING(mustBeNumericOrLogical)
+
+@DOCSTRING(mustBePositive)
+
+@DOCSTRING(mustBeReal)
+
+@node Parsing Arguments
+@subsection Parsing Arguments
+
+If none of the preceding validation functions is sufficient there is also
+the class @code{inputParser} which can perform extremely complex input
+checking for functions.
+
+@DOCSTRING(inputParser)
+
 @node Function Files
 @section Function Files
 @cindex function file
--- a/scripts/miscellaneous/mustBeNonzero.m	Wed Jan 22 00:26:59 2020 +0900
+++ b/scripts/miscellaneous/mustBeNonzero.m	Wed Jan 22 01:20:33 2020 +0900
@@ -24,7 +24,7 @@
 ########################################################################
 
 ## -*- texinfo -*-
-## @deftypefn {} {} {mustBeNonzero (@var{x})
+## @deftypefn {} {} mustBeNonzero (@var{x})
 ##
 ## Requires that input @var{x} is not zero.
 ##