changeset 32249:120134e43537

doc: Refine optimset, optimget docstring on paramter matching. (bug #64525) * optimget.m, optimset.m: Clarify that pattern matching is case insensitive and works by matching characters at the start of the parameter name. Remove double negatives from notes about ignoring non-standard options. Ensure consistent language used for options/parameters in both functions.
author Nicholas R. Jankowski <jankowski.nicholas@gmail.com>
date Thu, 10 Aug 2023 11:26:38 -0400
parents 3df98fee838b
children a279f26c2e65
files scripts/optimization/optimget.m scripts/optimization/optimset.m
diffstat 2 files changed, 22 insertions(+), 19 deletions(-) [+]
line wrap: on
line diff
--- a/scripts/optimization/optimget.m	Wed Aug 09 16:06:57 2023 -0400
+++ b/scripts/optimization/optimget.m	Thu Aug 10 11:26:38 2023 -0400
@@ -33,15 +33,17 @@
 ## supplied, otherwise return an empty matrix.
 ##
 ## If @var{par} does not exactly match the name of a standard parameter,
-## @code{optimget} will attempt to expand the name to match a standard
-## parameter and will return that parameter's value if a match is found.
-## @code{optimget} produces an error if it finds multiple ambiguous matches.
-## If no standard parameter matches are found a warning is issued.  See
-## @code{optimset} for information about the standard options list.
+## @code{optimget} will attempt to match @var{par} to a standard parameter
+## and will return that parameter's value if a match is found.  Matching is
+## case insensitive and is based on character matching at the start of the
+## parameter name. @code{optimget} produces an error if it finds multiple
+## ambiguous matches. If no standard parameter matches are found a warning is
+## issued.  See @code{optimset} for information about the standard options
+## list.
 ##
-## Note that any non-standard field names in @var{options} are ignored when
-## matching option names, and @var{par} will always be expanded
-## to match a standard option even if an exact non-standard match exists.  The
+## Note:  Only parameter names from the standard list are considered when
+## matching short parameter names, and @var{par} will always be expanded to
+## match a standard parameter even if an exact non-standard match exists.  The
 ## value of a non-standard parameter that is ambigious with one or more
 ## standard parameters cannot be returned by @code{optimget} and can only be
 ## accessed using @code{getfield} or dot notation for structs.
--- a/scripts/optimization/optimset.m	Wed Aug 09 16:06:57 2023 -0400
+++ b/scripts/optimization/optimset.m	Thu Aug 10 11:26:38 2023 -0400
@@ -45,11 +45,12 @@
 ## structure @var{new}.
 ##
 ## If @var{par} does not exactly match the name of a standard parameter,
-## @code{optimset} will attempt to expand the name to match a standard
-## parameter and will set the value of that parameter if a match is found.
-## @code{optimset} produces an error if it finds multiple ambiguous matches.
-## If no standard parameter matches are found a warning is issued and the
-## non-standard parameter is created.
+## @code{optimset} will attempt to match @var{par} to a standard parameter
+## and will set the value of that parameter if a match is found.  Matching is
+## case insensitive and is based on character matching at the start of the
+## parameter name.  @code{optimset} produces an error if it finds multiple
+## ambiguous matches.  If no standard parameter matches are found a warning is
+## issued and the non-standard parameter is created.
 ##
 ## Standard list of valid parameters:
 ##
@@ -128,12 +129,12 @@
 ## updated valid parameters list can be queried using the no-argument form of
 ## @code{optimset}.
 ##
-## Note 1:  Any non-standard field names in @var{old} are ignored when
-## matching parameter names, and @var{par} will always match to a standard
-## parameter even if an exact non-standard match exists.  The value of a
-## non-standard parameter that is ambigious with one or more standard
-## parameters cannot be set by @code{optimset} and can only be set using
-## @code{setfield} or dot notation for structs.
+## Note 1:  Only parameter names from the standard list are considered when
+## matching short parameter names, and @var{par} will always be expanded
+## to match a standard parameter even if an exact non-standard match exists.
+## The value of a non-standard parameter that is ambigious with one or more
+## standard parameters cannot be set by @code{optimset} and can only be set
+## using @code{setfield} or dot notation for structs.
 ##
 ## Note 2:  The optimization options structure is primarily intended for
 ## manipulation of known parameters by @code{optimset} and @code{optimget}.