# HG changeset patch
# User Rik <rik@octave.org>
# Date 1411442721 25200
# Node ID e09318118fd6190cd9e3f2be99dcf5d1462f8e4c
# Parent  adb102face2d7446ce229b1b2751d2809266e381
doc: Add note to gamma docstring about using gammaln when input is large.

* gammainc.cc (Fgammainc): Change seealso link to gammaln from lgamma.

* mappers.cc (Fgamma): Add note to docstring about using gammaln to preserve
precision when input to gamma is large.

* mappers.cc (Flgamma): Put gammaln first in docstring.

diff -r adb102face2d -r e09318118fd6 libinterp/corefcn/gammainc.cc
--- a/libinterp/corefcn/gammainc.cc	Mon Sep 22 20:24:42 2014 -0700
+++ b/libinterp/corefcn/gammainc.cc	Mon Sep 22 20:25:21 2014 -0700
@@ -73,7 +73,7 @@
 @example\n\
 gammainc (@var{x}, @var{a}) @equiv{} 1 - gammainc (@var{x}, @var{a}, \"upper\")\n\
 @end example\n\
-@seealso{gamma, lgamma}\n\
+@seealso{gamma, gammaln}\n\
 @end deftypefn")
 {
   octave_value retval;
diff -r adb102face2d -r e09318118fd6 libinterp/corefcn/mappers.cc
--- a/libinterp/corefcn/mappers.cc	Mon Sep 22 20:24:42 2014 -0700
+++ b/libinterp/corefcn/mappers.cc	Mon Sep 22 20:25:21 2014 -0700
@@ -1024,7 +1024,13 @@
 @end example\n\
 \n\
 @end ifnottex\n\
-@seealso{gammainc, lgamma}\n\
+\n\
+Programming Note: The gamma function can grow quite large even for small\n\
+input values.  In many cases it may be preferable to use the natural\n\
+logarithm of the gamma function (@code{gammaln}) in calculations to minimize\n\
+loss of precision.  The final result is then\n\
+@code{exp (@var{result_using_gammaln}).}\n\
+@seealso{gammainc, gammaln, factorial}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -1574,8 +1580,8 @@
 
 DEFUN (lgamma, args, ,
        "-*- texinfo -*-\n\
-@deftypefn  {Mapping Function} {} lgamma (@var{x})\n\
-@deftypefnx {Mapping Function} {} gammaln (@var{x})\n\
+@deftypefn  {Mapping Function} {} gammaln (@var{x})\n\
+@deftypefnx {Mapping Function} {} lgamma (@var{x})\n\
 Return the natural logarithm of the gamma function of @var{x}.\n\
 @seealso{gamma, gammainc}\n\
 @end deftypefn")