# HG changeset patch
# User jwe
# Date 774908278 0
# Node ID 95ee5e3301799c1a1faeaee01519c24fb893ca09
# Parent  75a371805554710195a7702a606a711d51c32386
[project @ 1994-07-22 20:17:58 by jwe]

diff -r 75a371805554 -r 95ee5e330179 src/defun-dld.h
--- a/src/defun-dld.h	Fri Jul 22 19:45:00 1994 +0000
+++ b/src/defun-dld.h	Fri Jul 22 20:17:58 1994 +0000
@@ -30,6 +30,12 @@
 
 #include "defun-int.h"
 
+// Define a builtin function that may be loaded dynamically at run
+// time.
+//
+// If Octave is not configured for dynamic linking of builtin
+// functions, this is exactly like DEFUN.
+
 #define DEFUN_DLD(name, fname, sname, nargin_max, nargout_max, doc) \
   DEFUN_INTERNAL (name, fname, sname, nargin_max, nargout_max, 0, doc)
 
diff -r 75a371805554 -r 95ee5e330179 src/defun-int.h
--- a/src/defun-int.h	Fri Jul 22 19:45:00 1994 +0000
+++ b/src/defun-int.h	Fri Jul 22 20:17:58 1994 +0000
@@ -24,8 +24,16 @@
 #if !defined (octave_defun_int_h)
 #define octave_defun_int_h 1
 
+// MAKE_BUILTINS is defined to extract function names and related
+// information and create the *.def files that are eventually used to
+// create the buitlins.cc file.
+
 #ifdef MAKE_BUILTINS
 
+// Generate code to install name in the symbol table.  The script
+// mkdefs will create a .def file for every .cc file that uses DEFUN,
+// DEFUN_TEXT, or DEFUN_DLD.
+
 #define DEFUN_INTERNAL(name, fname, sname, nargin_max, nargout_max, \
 		       is_text_fcn, doc) \
   BEGIN_INSTALL_BUILTIN \
@@ -35,18 +43,32 @@
     install_builtin_function (&sname); \
   END_INSTALL_BUILTIN
 
-#define DEFALIAS_INTERNAL(alias, name)
+// Generate code for making another name for an existing function.
+
+#define DEFALIAS_INTERNAL(alias, name) \
+  BEGIN_INSTALL_BUILTIN \
+  alias_builtin (#alias, #name); \
+  END_INSTALL_BUILTIN
 
 #else /* ! MAKE_BUILTINS */
 
+// Generate the first line of the function definition.  This ensures
+// that the internal functions all have the same signature.
+
 #define DEFUN_INTERNAL(name, fname, sname, nargin_max, nargout_max, \
 		       is_text_fcn, doc) \
   DECLARE_FUN(fname)
 
-#define DEFALIAS_INTERNAL(alias, name)
+// No definition is required for an alias.
+
+#define DEFALIAS_INTERNAL(name, alias)
 
 #endif /* ! MAKE_BUILTINS */
 
+// Declare an internal function named fname.  This is the interface
+// used by all internal functions in Octave that are also callable
+// from the Octave language.
+
 #define DECLARE_FUN(fname) \
   Octave_object \
   fname (const Octave_object& args, int nargout)
diff -r 75a371805554 -r 95ee5e330179 src/defun.h
--- a/src/defun.h	Fri Jul 22 19:45:00 1994 +0000
+++ b/src/defun.h	Fri Jul 22 20:17:58 1994 +0000
@@ -30,6 +30,30 @@
 
 #include "defun-int.h"
 
+// Define a builtin variable.
+//
+//   name is the name of the variable, as a string.
+//
+//   sname is the name of the structure that is used to hold
+//     information about the variable, and that is passed to
+//     install_builtin_variable to register it in the symbol table.
+//     By convention, it is constructed by prefixing name with the
+//     character S.
+//
+//   ins_as_fcn is a flag that says whether to install the variable as
+//     if it were a function (allowing the name to also be used as a
+//     variable by users, but recover its original definition if cleared).
+//
+//   eternal is a flag that says whether it should be possible to
+//     clear the variable.  Most builtin variables are eternal, and
+//     cannot be cleared.
+//
+//   sv_fcn is a pointer to a function that should be called whenever
+//     this variable is given a new value.  It can be 0 if there is no
+//     function to call.  See also the code in user-prefs.cc.
+//
+//   doc is the simple help text for this variable.
+
 #define DEFVAR(name, sname, defn, inst_as_fcn, protect, \
 	       eternal, sv_fcn, doc) \
   do \
@@ -48,12 +72,70 @@
     } \
   while (0)
 
+// Define a builtin function.
+//
+//   name is the name of the function, as a string.
+//
+//   fname is the name of the C++ function.  By convention, it is
+//     constructed by prefixing name with the character F.
+//
+//   sname is the name of the structure that is used to hold
+//     information about the function, and that is passed to
+//     install_builtin_function to register the function in the symbol
+//     table.  By convention, it is constructed by prefixing name with
+//     the character S.
+//
+//   nargin_max is the maximum number of arguments this function can
+//     accept. XXX FIXME XXX -- is this really used now?
+//
+//   nargout_max is the maximum number of outputs this function can
+//   produce.  XXX FIXME XXX -- is this really used now?
+//
+//   doc is the simple help text for the function.
+
 #define DEFUN(name, fname, sname, nargin_max, nargout_max, doc) \
   DEFUN_INTERNAL (name, fname, sname, nargin_max, nargout_max, 0, doc)
 
+// Define a builtin text-style function.
+//
+// This is like DEFUN, except that it defines a function that can be
+// called from the Octave language without using parenthesis to
+// surround the arguments). 
+
 #define DEFUN_TEXT(name, fname, sname, nargin_max, nargout_max, doc) \
   DEFUN_INTERNAL (name, fname, sname, nargin_max, nargout_max, 1, doc)
 
+// Define a mapper function.
+//
+//   name is the name of the function as a string
+//
+//   sname is the name of the structure that is used to hold
+//     information about the function, and that is passed to
+//     install_builtin_mapper to register the function in the symbol
+//     table.  By convention, it is constructed by prefixing name with
+//     the character S.
+//
+//   can_ret_cmplx_for_real is a flag that says whether this function
+//     can create a complex number given a real-valued  argument
+//     (e.g., sqrt (-1)).
+//
+//   lo is the lower bound of the range for which real arguments can
+//     become complex.  (e.g., lo == -Inf for sqrt).
+//
+//   hi is the upper bound of the range for which real arguments can
+//     become complex.  (e.g., hi == 0 for sqrt).
+//
+//   d_d_map is a pointer to a function that should be called for real
+//     arguments that are expected to create real results.
+//
+//   d_c_map is a pointer to a function that should be called for real
+//     arguments that are expected to create complex results.
+//
+//   c_c_map is a pointer to a function that should be called for
+//     complex arguments that are expected to create complex results.
+//
+//   doc is the simple help text for the function.
+
 #define DEFUN_MAPPER(name, sname, can_ret_cmplx_for_real, lo, hi, \
 		     d_d_map, d_c_map, c_c_map, doc) \
   do \
@@ -73,26 +155,11 @@
     } \
   while (0)
 
-#define DEFALIAS(alias, name) DEFALIAS_INTERNAL (alias, name)
-
-#ifdef MAKE_BUILTINS
+// Make alias another name for the existing function name.  This macro
+// must be used in the same file where name is defined, after the
+// definition for name.
 
-#define DEFUN_INTERNAL(name, fname, sname, nargin_max, nargout_max, \
-		       is_text_fcn, doc) \
-  BEGIN_INSTALL_BUILTIN \
-    extern DECLARE_FUN(fname); \
-    static builtin_function sname = \
-      { name, nargin_max, nargout_max, is_text_fcn, fname, doc }; \
-    install_builtin_function (&sname); \
-  END_INSTALL_BUILTIN
-
-#else /* ! MAKE_BUILTINS */
-
-#define DEFUN_INTERNAL(name, fname, sname, nargin_max, nargout_max, \
-		       is_text_fcn, doc) \
-  DECLARE_FUN(fname)
-
-#endif /* ! MAKE_BUILTINS */
+#define DEFALIAS(name, alias) DEFALIAS_INTERNAL (name, alias)
 
 #endif