Mercurial > hg > octave-lyh

diff src/help.cc @ 14169:c0ca47ab7641 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Better explain which complex result is chosen by .^ * expr.txi: Explain which complex root is chosen and how to choose a real one if preferred. * data.cc (power): Ditto. * help.cc (.^, .**): Ditto. (^, **): Suggest using real-valued functions.
author Jordi Gutiérrez Hermoso <jordigh@octave.org>
date Sun, 08 Jan 2012 15:24:53 -0500
parents 72c96de7a403
children 2ced2f59f523
line wrap: on
line diff
--- a/src/help.cc
+++ b/src/help.cc
@@ -239,15 +239,19 @@
   pair_type ("**",
     "-*- texinfo -*-\n\
 @deftypefn {Operator} {} **\n\
-Power operator.\n\
-@seealso{power, ^, .**, .^}\n\
+Power operator. This may return complex results for real inputs. Use\n\
+@code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\
+real results when possible.\n\
+@seealso{power, ^, .**, .^, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn"),
 
   pair_type ("^",
     "-*- texinfo -*-\n\
 @deftypefn {Operator} {} ^\n\
-Power operator.\n\
-@seealso{power, **, .^, .**}\n\
+Power operator. This may return complex results for real inputs. Use\n\
+@code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\
+real results when possible.\n\
+@seealso{power, **, .^, .**, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn"),
 
   pair_type ("+",
@@ -304,15 +308,21 @@
   pair_type (".**",
     "-*- texinfo -*-\n\
 @deftypefn {Operator} {} .*\n\
-Element by element power operator.\n\
-@seealso{**, ^, .^, power}\n\
+Element by element power operator. If several complex results are possible,\n\
+returns the one with smallest nonnegative argument (angle). Use\n\
+@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\
+real result is preferred.\n\
+@seealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn"),
 
   pair_type (".^",
     "-*- texinfo -*-\n\
 @deftypefn {Operator} {} .^\n\
-Element by element power operator.\n\
-@seealso{.**, ^, **, power}\n\
+Element by element power operator. If several complex results are possible,\n\
+returns the one with smallest nonnegative argument (angle). Use\n\
+@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\
+real result is preferred.\n\
+@seealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn"),
 
   pair_type ("./",