built-in functions are now self-documenting

pub/src/func.cpp

@@ -315,7 +315,7 @@ string NFunctions::list()
         } else { // functions
             if( f->prec!=prec )
                 ret += "\nFunctions (number of arguments):\n";
-            ret += "  " + f->txt + " (" + strg(f->narg) + ")\n";
+            ret += "  " + f->txt + f->com + "\n";
         }
         prec = f->prec;
     }
@@ -354,57 +354,111 @@ void NFunctions::initialize(void) {
     CFunc( "?:",  func_cond, deri_cond, 13 ).register_me();
 
 // f( 1 arg )
-    CFunc( "ln",   func_ln,    deri_ln     ).register_me();
-    CFunc( "lg",   func_lg,    deri_lg     ).register_me();
-    CFunc( "sqrt", func_sqrt,  deri_sqrt   ).register_me();
-    CFunc( "abs",  func_abs,   deri_abs    ).register_me();
-    CFunc( "exp",  func_exp,   deri_exp    ).register_me();
-    CFunc( "sin",  func_sin    ).register_me();
-    CFunc( "cos",  func_cos    ).register_me();
-    CFunc( "tan",  func_tan    ).register_me();
-    CFunc( "cot",  func_cot    ).register_me();
-    CFunc( "sind", func_sind   ).register_me();
-    CFunc( "cosd", func_cosd   ).register_me();
-    CFunc( "tand", func_tand   ).register_me();
-    CFunc( "cotd", func_cotd   ).register_me();
-    CFunc( "asin", func_asin   ).register_me();
-    CFunc( "acos", func_acos   ).register_me();
-    CFunc( "atan", func_atan   ).register_me();
-    CFunc( "acot", func_acot   ).register_me();
-    CFunc( "asind",func_asind  ).register_me();
-    CFunc( "acosd",func_acosd  ).register_me();
-    CFunc( "atand",func_atand  ).register_me();
-    CFunc( "acotd",func_acotd  ).register_me();
-    CFunc( "sinh", func_sinh   ).register_me();
-    CFunc( "cosh", func_cosh   ).register_me();
-    CFunc( "tanh", func_tanh   ).register_me();
-    CFunc( "coth", func_coth   ).register_me();
-    CFunc( "gamma",func_gamma  ).register_me();
-    CFunc( "erfP", func_erfP   ).register_me();
-    CFunc( "erfQ", func_erfQ   ).register_me();
-    CFunc( "erf",  func_erf    ).register_me();
-    CFunc( "erfc", func_erfc   ).register_me();
-    CFunc( "sinc", func_sinc   ).register_me();
-    CFunc( "ceil", func_ceil   ).register_me();
-    CFunc( "floor",func_floor  ).register_me();
-    CFunc( "nint", func_nint   ).register_me();
+    CFunc( "ln",   func_ln,    deri_ln, 0,
+           "(x): natural logarithm of x, or 0 if x<=0" ).register_me();
+    CFunc( "lg",   func_lg,    deri_lg, 0,
+           "(x): decadic logarithm of x, or 0 if x<=0" ).register_me();
+    CFunc( "sqrt", func_sqrt,  deri_sqrt, 0,
+           "(x): square root of x, or 0 if x<0" ).register_me();
+    CFunc( "abs",  func_abs,   deri_abs, 0,
+           "(x): absolute value of x" ).register_me();
+    CFunc( "exp",  func_exp,   deri_exp, 0,
+           "(x): exponential function of x" ).register_me();
+    CFunc( "sin",  func_sin, 0, 0,
+           "(x): sine of x (where x in radian)" ).register_me();
+    CFunc( "cos",  func_cos, 0, 0,
+           "(x): cosine of x (where x in radian)" ).register_me();
+    CFunc( "tan",  func_tan, 0, 0,
+           "(x): tangent of x (where x in radian)" ).register_me();
+    CFunc( "cot",  func_cot, 0, 0,
+           "(x): cotangent of x (where x in radian)" ).register_me();
+    CFunc( "sind",  func_sin, 0, 0,
+           "(x): sine of x (where x in degrees)" ).register_me();
+    CFunc( "cosd",  func_cos, 0, 0,
+           "(x): cosine of x (where x in degrees)" ).register_me();
+    CFunc( "tand",  func_tan, 0, 0,
+           "(x): tangent of x (where x in degrees)" ).register_me();
+    CFunc( "cotd",  func_cot, 0, 0,
+           "(x): cotangent of x (where x in degrees)" ).register_me();
+    CFunc( "asin", func_asin, 0, 0,
+           "(x): arc sine of x (result is in radian; return 0 if |x|>1)"
+        ).register_me();
+    CFunc( "acos", func_acos, 0, 0,
+           "(x): arc cosine of x (result is in radian; return 0 if |x|>1)"
+        ).register_me();
+    CFunc( "atan", func_atan, 0, 0,
+           "(x): arc tangent of x (result is in radian)" ).register_me();
+    CFunc( "acot", func_acot, 0, 0,
+           "(x): arc cotangent of x (result is in radian)" ).register_me();
+    CFunc( "asind", func_asind, 0, 0,
+           "(x): arc sine of x (result is in degrees; return 0 if |x|>1)"
+        ).register_me();
+    CFunc( "acosd", func_acosd, 0, 0,
+           "(x): arc cosine of x (result is in degrees; return 0 if |x|>1)"
+        ).register_me();
+    CFunc( "atand", func_atand, 0, 0,
+           "(x): arc tangent of x (result is in degrees)" ).register_me();
+    CFunc( "acotd", func_acotd, 0, 0,
+           "(x): arc cotangent of x (result is in degrees)" ).register_me();
+    CFunc( "sinh", func_sinh, 0, 0,
+           "(x): hyperbolic sine of x" ).register_me();
+    CFunc( "cosh", func_cosh, 0, 0,
+           "(x): hyperbolic cosine of x" ).register_me();
+    CFunc( "tanh", func_tanh, 0, 0,
+           "(x): hyperbolic tangent of x" ).register_me();
+    CFunc( "coth", func_coth, 0, 0,
+           "(x): hyperbolic tangent of x"   ).register_me();
+    CFunc( "gamma",func_gamma, 0, 0,
+        "(x): gamma function of x (i.e. factorial of x-1)" ).register_me();
+    CFunc( "erfP", func_erfP, 0, 0,
+        "(x): ?" ).register_me();
+    CFunc( "erfQ", func_erfQ , 0, 0,
+        "(x): ?"  ).register_me();
+    CFunc( "erf",  func_erf, 0, 0,
+        "(x): error function of x" ).register_me();
+    CFunc( "erfc", func_erfc, 0, 0,
+        "(x): complementary error function of x" ).register_me();
+    CFunc( "sinc", func_sinc, 0, 0,
+        "(x): sinus cardinalis, sin(x)/x" ).register_me();
+    CFunc( "ceil", func_ceil, 0, 0,
+        "(x): the smallest integer i with i>=x" ).register_me();
+    CFunc( "floor",func_floor, 0, 0,
+        "(x): the largest integer i with i<=x" ).register_me();
+    CFunc( "nint", func_nint, 0, 0,
+        "(x): the integer nearest to x" ).register_me();
 
 // f(2 args)
-    CFunc( "min",  func_min    ).register_me();
-    CFunc( "max",  func_max    ).register_me();
-    CFunc( "ran",  func_ran    ).register_me();
-
-    CFunc( "kwwc", func_kwwc   ).register_me();
-    CFunc( "kwws", func_kwws   ).register_me();
-
-    CFunc( "gauss",   func_gauss).register_me();
-    CFunc( "gnn",     func_gaussnn ).register_me();
-    CFunc( "cauchy",  func_cauchy ).register_me();
+    CFunc( "min",  func_min, 0, 0,
+        "(x,y): the smaller of the two arguments x and y" ).register_me();
+    CFunc( "max",  func_max, 0, 0,
+        "(x,y): the smaller of the two arguments x and y" ).register_me();
+    CFunc( "ran",  func_ran, 0, 0,
+        "(x,y): a random number between x and y" ).register_me();
+
+    CFunc( "kwwc", func_kwwc, 0, 0,
+        "(x,b): Fourier cosine transform of exp(x^b)" ).register_me();
+    CFunc( "kwws", func_kwws, 0, 0,
+        "(x,b): Fourier sine transform of exp(x^b)" ).register_me();
+
+    CFunc( "gauss",   func_gauss, 0, 0,
+           "(x,s): the normalized Gaussian exp(-x^2/2/s^2)/sqrt(2 pi)/s"
+        ).register_me();
+    CFunc( "gnn",     func_gaussnn, 0, 0,
+        "(x,s): the unnormalized Gaussian exp(-x^2/2/s^2)" ).register_me();
+    CFunc( "cauchy",  func_cauchy, 0, 0,
+        "(x,w): the Cauchy-Lorentz function ?/(x^2+w^2)" ).register_me();
 
 // f(3 args)
-    CFunc( "q4w",      func_q4w    ).register_me();
-    CFunc( "cauchy2",  func_cauchy2 ).register_me();
-    CFunc( "skww",     func_skww    ).register_me();
-    CFunc( "rehavneg", func_re_havneg    ).register_me();
-    CFunc( "imhavneg", func_im_havneg    ).register_me();
+    CFunc( "q4w",      func_q4w, 0, 0,
+        "(x,y,z): ?" ).register_me();
+    CFunc( "cauchy2",  func_cauchy2, 0, 0,
+        "(x,y,z): ?" ).register_me();
+    CFunc( "skww",     func_skww, 0, 0,
+        "(x,y,z): ?" ).register_me();
+    CFunc( "rehavneg", func_re_havneg, 0, 0,
+        "(x,y,z): real part of the Havriliak-Negami function"
+        ).register_me();
+    CFunc( "imhavneg", func_im_havneg, 0, 0,
+        "(x,y,z): imaginary part of the Havriliak-Negami function"
+        ).register_me();
 }

pub/src/func.h

@@ -18,16 +18,17 @@ class CFunc { // public (short) interface => TAKE CARE
     deri_f2 d2;
     deri_f3 d3;
     int prec;
+    string com;
     class CCoord coord( class CCoord *co ) const;
     class CCoord coord( class CCoord *co1, class CCoord *co2 ) const;
     class CCoord coord( class CCoord *co1, class CCoord *co2,
                         class CCoord *co3 ) const;
-    CFunc( string _txt, func_f1 _f1, deri_f1 _d1=0, uint _prec=0 )
-        : txt(_txt), narg(1), f1(_f1), d1(_d1), prec(_prec) {};
-    CFunc( string _txt, func_f2 _f2, deri_f2 _d2=0, uint _prec=0 )
-        : txt(_txt), narg(2), f2(_f2), d2(_d2), prec(_prec) {};
-    CFunc( string _txt, func_f3 _f3, deri_f3 _d3=0, uint _prec=0 )
-        : txt(_txt), narg(3), f3(_f3), d3(_d3), prec(_prec) {};
+    CFunc( string _txt, func_f1 _f1, deri_f1 _d1, uint _prec, string _com="" )
+        : txt(_txt), narg(1), f1(_f1), d1(_d1), prec(_prec), com(_com) {};
+    CFunc( string _txt, func_f2 _f2, deri_f2 _d2, uint _prec, string _com="" )
+        : txt(_txt), narg(2), f2(_f2), d2(_d2), prec(_prec), com(_com) {};
+    CFunc( string _txt, func_f3 _f3, deri_f3 _d3, uint _prec, string _com="" )
+        : txt(_txt), narg(3), f3(_f3), d3(_d3), prec(_prec), com(_com) {};
 
     void register_me() const;
 };