Mercurial > octave
changeset 24194:3333ca37c038
doc: improve Doxygen comments for DEFUN* macros.
* libinterp/corefcn/defun.h (DEFUN, DEFUNX, DEFCONSTFUN, DEFMETHOD, DEFMETHODX,
DEFCONSTMETHOD, DEFALIAS): reorder macros as given in the list and add Doxygen
comments.
* libinterp/corefcn/defun-dld.h (DEFUN_DLD, DEFMETHOD_DLD): add Doxygen
comments.
| author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
|---|---|
| date | Fri, 03 Nov 2017 15:49:18 +0100 |
| parents | b7e5486e7bff |
| children | d3dc76efb38b |
| files | libinterp/corefcn/defun-dld.h libinterp/corefcn/defun.h |
| diffstat | 2 files changed, 212 insertions(+), 34 deletions(-) [+] |
line wrap: on
line diff
--- a/libinterp/corefcn/defun-dld.h Fri Nov 03 15:44:02 2017 +0100 +++ b/libinterp/corefcn/defun-dld.h Fri Nov 03 15:49:18 2017 +0100 @@ -31,16 +31,29 @@ #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 the same as DEFUN, except that it will generate -// an extra externally visible function. -// -// The FORWARD_DECLARE_FUN is for the benefit of the installer function. -// -// The DECLARE_FUN is for the definition of the function. +//! Macro to define an at run time dynamically loadable builtin function. +//! +//! For detailed information, see \ref Macros. +//! +//! @param name The **unqouted** name of the function that should be installed +//! on the `octave::symbol_table` and can be called by the +//! interpreter. Internally, the function name is prepended by an +//! `F`. +//! @param args_name The name of the octave_value_list variable used to pass +//! the argument list to this function. If this value is +//! omitted, the function cannot access the argument list. +//! @param nargout_name The name of the `int` variable used to pass the number +//! of output arguments this function is expected to +//! produce from the caller. If this value is +//! omitted, the function cannot access this number. +//! @param doc Texinfo help text (docstring) for the function. +//! +//! @see DEFMETHOD_DLD + +// The order of this macro for name = foo is: +// 1. Forward declaration of Ffoo. +// 2. Definition of installation function Gfoo. +// 3. Definition of Ffoo. #define DEFUN_DLD(name, args_name, nargout_name, doc) \ FORWARD_DECLARE_FUN (name); \ @@ -52,6 +65,34 @@ DEFINE_FUNX_INSTALLER_FUN (name, fname, gname, doc) \ DECLARE_FUNX (fname, args_name, nargout_name) +//! Macro to define an at run time dynamically loadable builtin method. +//! +//! For detailed information, see \ref Macros. +//! +//! @param name The **unqouted** name of the method that should be installed +//! on the `octave::symbol_table` and can be called by the +//! interpreter. Internally, the method name is prepended by an +//! `F`. +//! @param interp_name The name of the `octave::interpreter` reference that can +//! be used by this method. If this value is omitted, +//! there is no access to the interpreter and one should +//! use #DEFUN to define a function instead. +//! @param args_name The name of the octave_value_list variable used to pass +//! the argument list to this method. If this value is +//! omitted, the method cannot access the argument list. +//! @param nargout_name The name of the `int` variable used to pass the number +//! of output arguments this method is expected to +//! produce from the caller. If this value is +//! omitted, the method cannot access this number. +//! @param doc Texinfo help text (docstring) for the method. +//! +//! @see DEFUN_DLD + +// The order of this macro for name = foo is again: +// 1. Forward declaration of Ffoo. +// 2. Definition of installation function Gfoo. +// 3. Definition of Ffoo. + #define DEFMETHOD_DLD(name, interp_name, args_name, nargout_name, doc) \ FORWARD_DECLARE_METHOD (name); \ DEFINE_FUN_INSTALLER_FUN (name, doc) \
--- a/libinterp/corefcn/defun.h Fri Nov 03 15:44:02 2017 +0100 +++ b/libinterp/corefcn/defun.h Fri Nov 03 15:49:18 2017 +0100 @@ -31,45 +31,182 @@ #include "defun-int.h" -// Define a builtin function. -// -// name is the name of the function, unqouted. -// -// args_name is the name of the octave_value_list variable used to pass -// the argument list to this function. -// -// nargout_name is the name of the int variable used to pass the -// number of output arguments this function is expected to produce. -// -// doc is the simple help text for the function. +//! Macro to define a builtin function. +//! +//! For detailed information, see \ref Macros. +//! +//! @param name The **unqouted** name of the function that should be installed +//! on the `octave::symbol_table` and can be called by the +//! interpreter. Internally, the function name is prepended by an +//! `F`. +//! @param args_name The name of the octave_value_list variable used to pass +//! the argument list to this function. If this value is +//! omitted, the function cannot access the argument list. +//! @param nargout_name The name of the `int` variable used to pass the number +//! of output arguments this function is expected to +//! produce from the caller. If this value is +//! omitted, the function cannot access this number. +//! @param doc Texinfo help text (docstring) for the function. +//! +//! @see DEFUNX, DEFCONSTFUN #define DEFUN(name, args_name, nargout_name, doc) \ DECLARE_FUN (name, args_name, nargout_name) +//! Macro to define a builtin function with certain internal name. +//! +//! @warning Consider to use #DEFUN, unless you have good reason. +//! +//! For detailed information, see \ref Macros. +//! +//! This macro can be used when @p name cannot be used directly (for example if +//! it is already defined as a macro). In that case, @p name is already a +//! quoted string (thus unaffected by macros), and the internal name of the +//! function is given by @p fname. +//! +//! @param name The **qouted** name of the function that should be callable +//! by the interpreter. +//! @param fname The internal **unqouted** name of the function. This internal +//! name is by convention prepended by an `F`. +//! @param args_name The name of the octave_value_list variable used to pass +//! the argument list to this function. If this value is +//! omitted, the function cannot access the argument list. +//! @param nargout_name The name of the `int` variable used to pass the number +//! of output arguments this function is expected to +//! produce from the caller. If this value is +//! omitted, the function cannot access this number. +//! @param doc Texinfo help text (docstring) for the function. +//! +//! @see DEFUN, DEFCONSTFUN + +#define DEFUNX(name, fname, args_name, nargout_name, doc) \ + DECLARE_FUNX (fname, args_name, nargout_name) + +//! Macro to define a builtin function that cannot be hidden by a variable. +//! +//! @warning Consider to use #DEFUN, unless you have good reason. +//! +//! For detailed information, see \ref Macros. +//! +//! The function gets installed to the `octave::symbol_table` in a way, such +//! that no variable is allowed to hide this function name. +//! +//! @param name The **unqouted** name of the function that should be installed +//! on the `octave::symbol_table` and can be called by the +//! interpreter. Internally, the function name is prepended by an +//! `F`. +//! @param args_name The name of the octave_value_list variable used to pass +//! the argument list to this function. If this value is +//! omitted, the function cannot access the argument list. +//! @param nargout_name The name of the `int` variable used to pass the number +//! of output arguments this function is expected to +//! produce from the caller. If this value is +//! omitted, the function cannot access this number. +//! @param doc Texinfo help text (docstring) for the function. +//! +//! @see DEFUN, DEFUNX + +#define DEFCONSTFUN(name, args_name, nargout_name, doc) \ + DECLARE_FUN (name, args_name, nargout_name) + +//! Macro to define a builtin method. +//! +//! For detailed information, see \ref Macros. +//! +//! @param name The **unqouted** name of the method that should be installed +//! on the `octave::symbol_table` and can be called by the +//! interpreter. Internally, the method name is prepended by an +//! `F`. +//! @param interp_name The name of the `octave::interpreter` reference that can +//! be used by this method. If this value is omitted, +//! there is no access to the interpreter and one should +//! use #DEFUN to define a function instead. +//! @param args_name The name of the octave_value_list variable used to pass +//! the argument list to this method. If this value is +//! omitted, the method cannot access the argument list. +//! @param nargout_name The name of the `int` variable used to pass the number +//! of output arguments this method is expected to +//! produce from the caller. If this value is +//! omitted, the method cannot access this number. +//! @param doc Texinfo help text (docstring) for the method. +//! +//! @see DEFMETHODX, DEFCONSTMETHOD + #define DEFMETHOD(name, interp_name, args_name, nargout_name, doc) \ DECLARE_METHOD (name, interp_name, args_name, nargout_name) -// This one can be used when 'name' cannot be used directly (if it is -// already defined as a macro). In that case, name is already a -// quoted string, and the internal name of the function must be passed -// too (the convention is to use a prefix of "F", so "foo" becomes "Ffoo"). - -#define DEFUNX(name, fname, args_name, nargout_name, doc) \ - DECLARE_FUNX (fname, args_name, nargout_name) +//! Macro to define a builtin method with certain internal name. +//! +//! @warning Consider to use #DEFMETHOD, unless you have good reason. +//! +//! For detailed information, see \ref Macros. +//! +//! This macro can be used when @p name cannot be used directly (for example if +//! it is already defined as a macro). In that case, @p name is already a +//! quoted string (thus unaffected by macros), and the internal name of the +//! method is given by @p fname. +//! +//! @param name The **qouted** name of the method that should be callable +//! by the interpreter. +//! @param fname The internal **unqouted** name of the method. This internal +//! name is by convention prepended by an `F`. +//! @param interp_name The name of the `octave::interpreter` reference that can +//! be used by this method. If this value is omitted, +//! there is no access to the interpreter and one should +//! use #DEFUNX to define a function instead. +//! @param args_name The name of the octave_value_list variable used to pass +//! the argument list to this method. If this value is +//! omitted, the method cannot access the argument list. +//! @param nargout_name The name of the `int` variable used to pass the number +//! of output arguments this method is expected to +//! produce from the caller. If this value is +//! omitted, the method cannot access this number. +//! @param doc Texinfo help text (docstring) for the method. +//! +//! @see DEFMETHOD, DEFCONSTMETHOD #define DEFMETHODX(name, fname, interp_name, args_name, nargout_name, doc) \ DECLARE_METHODX (fname, interp_name, args_name, nargout_name) -// This is a function with a name that can't be hidden by a variable. -#define DEFCONSTFUN(name, args_name, nargout_name, doc) \ - DECLARE_FUN (name, args_name, nargout_name) +//! Macro to define a builtin method that cannot be hidden by a variable. +//! +//! @warning Consider to use #DEFMETHOD, unless you have good reason. +//! +//! For detailed information, see \ref Macros. +//! +//! The method gets installed to the `octave::symbol_table` in a way, such +//! that no variable is allowed to hide this method name. +//! +//! @param name The **unqouted** name of the method that should be installed +//! on the `octave::symbol_table` and can be called by the +//! interpreter. Internally, the method name is prepended by an +//! `F`. +//! @param interp_name The name of the `octave::interpreter` reference that can +//! be used by this method. If this value is omitted, +//! there is no access to the interpreter and one should +//! use #DEFCONSTFUN to define a function instead. +//! @param args_name The name of the octave_value_list variable used to pass +//! the argument list to this method. If this value is +//! omitted, the method cannot access the argument list. +//! @param nargout_name The name of the `int` variable used to pass the number +//! of output arguments this method is expected to +//! produce from the caller. If this value is +//! omitted, the method cannot access this number. +//! @param doc Texinfo help text (docstring) for the method. +//! +//! @see DEFMETHOD, DEFMETHODX #define DEFCONSTMETHOD(name, interp_name, args_name, nargout_name, doc) \ DECLARE_METHOD (name, interp_name, args_name, nargout_name) -// Make alias another name for the existing function name. This macro -// is processed by the mkbuiltins to generate code in builtins.cc to -// create the alias in the symbol table. +//! Macro to define an alias for another existing function name. +//! +//! For detailed information, see \ref Macros. +//! +//! @param alias For another existing function name. +//! @param name The name of the other existing function. +//! +//! @see DEFUN #define DEFALIAS(alias, name)