Mercurial > octave

comparison libinterp/corefcn/defun.h @ 24194:3333ca37c038

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 8744d4ed8fb4
children 194eb4bd202b
comparison
equal deleted inserted replaced
24193:b7e5486e7bff 24194:3333ca37c038
29 # error defun.h and defun-dld.h both included in same file! 29 # error defun.h and defun-dld.h both included in same file!
30 #endif 30 #endif
31 31
32 #include "defun-int.h" 32 #include "defun-int.h"
33 33
34 // Define a builtin function. 34 //! Macro to define a builtin function.
35 // 35 //!
36 // name is the name of the function, unqouted. 36 //! For detailed information, see \ref Macros.
37 // 37 //!
38 // args_name is the name of the octave_value_list variable used to pass 38 //! @param name The **unqouted** name of the function that should be installed
39 // the argument list to this function. 39 //! on the `octave::symbol_table` and can be called by the
40 // 40 //! interpreter. Internally, the function name is prepended by an
41 // nargout_name is the name of the int variable used to pass the 41 //! `F`.
42 // number of output arguments this function is expected to produce. 42 //! @param args_name The name of the octave_value_list variable used to pass
43 // 43 //! the argument list to this function. If this value is
44 // doc is the simple help text for the function. 44 //! omitted, the function cannot access the argument list.
45 //! @param nargout_name The name of the `int` variable used to pass the number
46 //! of output arguments this function is expected to
47 //! produce from the caller. If this value is
48 //! omitted, the function cannot access this number.
49 //! @param doc Texinfo help text (docstring) for the function.
50 //!
51 //! @see DEFUNX, DEFCONSTFUN
45 52
46 #define DEFUN(name, args_name, nargout_name, doc) \ 53 #define DEFUN(name, args_name, nargout_name, doc) \
47 DECLARE_FUN (name, args_name, nargout_name) 54 DECLARE_FUN (name, args_name, nargout_name)
48 55
56 //! Macro to define a builtin function with certain internal name.
57 //!
58 //! @warning Consider to use #DEFUN, unless you have good reason.
59 //!
60 //! For detailed information, see \ref Macros.
61 //!
62 //! This macro can be used when @p name cannot be used directly (for example if
63 //! it is already defined as a macro). In that case, @p name is already a
64 //! quoted string (thus unaffected by macros), and the internal name of the
65 //! function is given by @p fname.
66 //!
67 //! @param name The **qouted** name of the function that should be callable
68 //! by the interpreter.
69 //! @param fname The internal **unqouted** name of the function. This internal
70 //! name is by convention prepended by an `F`.
71 //! @param args_name The name of the octave_value_list variable used to pass
72 //! the argument list to this function. If this value is
73 //! omitted, the function cannot access the argument list.
74 //! @param nargout_name The name of the `int` variable used to pass the number
75 //! of output arguments this function is expected to
76 //! produce from the caller. If this value is
77 //! omitted, the function cannot access this number.
78 //! @param doc Texinfo help text (docstring) for the function.
79 //!
80 //! @see DEFUN, DEFCONSTFUN
81
82 #define DEFUNX(name, fname, args_name, nargout_name, doc) \
83 DECLARE_FUNX (fname, args_name, nargout_name)
84
85 //! Macro to define a builtin function that cannot be hidden by a variable.
86 //!
87 //! @warning Consider to use #DEFUN, unless you have good reason.
88 //!
89 //! For detailed information, see \ref Macros.
90 //!
91 //! The function gets installed to the `octave::symbol_table` in a way, such
92 //! that no variable is allowed to hide this function name.
93 //!
94 //! @param name The **unqouted** name of the function that should be installed
95 //! on the `octave::symbol_table` and can be called by the
96 //! interpreter. Internally, the function name is prepended by an
97 //! `F`.
98 //! @param args_name The name of the octave_value_list variable used to pass
99 //! the argument list to this function. If this value is
100 //! omitted, the function cannot access the argument list.
101 //! @param nargout_name The name of the `int` variable used to pass the number
102 //! of output arguments this function is expected to
103 //! produce from the caller. If this value is
104 //! omitted, the function cannot access this number.
105 //! @param doc Texinfo help text (docstring) for the function.
106 //!
107 //! @see DEFUN, DEFUNX
108
109 #define DEFCONSTFUN(name, args_name, nargout_name, doc) \
110 DECLARE_FUN (name, args_name, nargout_name)
111
112 //! Macro to define a builtin method.
113 //!
114 //! For detailed information, see \ref Macros.
115 //!
116 //! @param name The **unqouted** name of the method that should be installed
117 //! on the `octave::symbol_table` and can be called by the
118 //! interpreter. Internally, the method name is prepended by an
119 //! `F`.
120 //! @param interp_name The name of the `octave::interpreter` reference that can
121 //! be used by this method. If this value is omitted,
122 //! there is no access to the interpreter and one should
123 //! use #DEFUN to define a function instead.
124 //! @param args_name The name of the octave_value_list variable used to pass
125 //! the argument list to this method. If this value is
126 //! omitted, the method cannot access the argument list.
127 //! @param nargout_name The name of the `int` variable used to pass the number
128 //! of output arguments this method is expected to
129 //! produce from the caller. If this value is
130 //! omitted, the method cannot access this number.
131 //! @param doc Texinfo help text (docstring) for the method.
132 //!
133 //! @see DEFMETHODX, DEFCONSTMETHOD
134
49 #define DEFMETHOD(name, interp_name, args_name, nargout_name, doc) \ 135 #define DEFMETHOD(name, interp_name, args_name, nargout_name, doc) \
50 DECLARE_METHOD (name, interp_name, args_name, nargout_name) 136 DECLARE_METHOD (name, interp_name, args_name, nargout_name)
51 137
52 // This one can be used when 'name' cannot be used directly (if it is 138 //! Macro to define a builtin method with certain internal name.
53 // already defined as a macro). In that case, name is already a 139 //!
54 // quoted string, and the internal name of the function must be passed 140 //! @warning Consider to use #DEFMETHOD, unless you have good reason.
55 // too (the convention is to use a prefix of "F", so "foo" becomes "Ffoo"). 141 //!
56 142 //! For detailed information, see \ref Macros.
57 #define DEFUNX(name, fname, args_name, nargout_name, doc) \ 143 //!
58 DECLARE_FUNX (fname, args_name, nargout_name) 144 //! This macro can be used when @p name cannot be used directly (for example if
145 //! it is already defined as a macro). In that case, @p name is already a
146 //! quoted string (thus unaffected by macros), and the internal name of the
147 //! method is given by @p fname.
148 //!
149 //! @param name The **qouted** name of the method that should be callable
150 //! by the interpreter.
151 //! @param fname The internal **unqouted** name of the method. This internal
152 //! name is by convention prepended by an `F`.
153 //! @param interp_name The name of the `octave::interpreter` reference that can
154 //! be used by this method. If this value is omitted,
155 //! there is no access to the interpreter and one should
156 //! use #DEFUNX to define a function instead.
157 //! @param args_name The name of the octave_value_list variable used to pass
158 //! the argument list to this method. If this value is
159 //! omitted, the method cannot access the argument list.
160 //! @param nargout_name The name of the `int` variable used to pass the number
161 //! of output arguments this method is expected to
162 //! produce from the caller. If this value is
163 //! omitted, the method cannot access this number.
164 //! @param doc Texinfo help text (docstring) for the method.
165 //!
166 //! @see DEFMETHOD, DEFCONSTMETHOD
59 167
60 #define DEFMETHODX(name, fname, interp_name, args_name, nargout_name, doc) \ 168 #define DEFMETHODX(name, fname, interp_name, args_name, nargout_name, doc) \
61 DECLARE_METHODX (fname, interp_name, args_name, nargout_name) 169 DECLARE_METHODX (fname, interp_name, args_name, nargout_name)
62 170
63 // This is a function with a name that can't be hidden by a variable. 171 //! Macro to define a builtin method that cannot be hidden by a variable.
64 #define DEFCONSTFUN(name, args_name, nargout_name, doc) \ 172 //!
65 DECLARE_FUN (name, args_name, nargout_name) 173 //! @warning Consider to use #DEFMETHOD, unless you have good reason.
174 //!
175 //! For detailed information, see \ref Macros.
176 //!
177 //! The method gets installed to the `octave::symbol_table` in a way, such
178 //! that no variable is allowed to hide this method name.
179 //!
180 //! @param name The **unqouted** name of the method that should be installed
181 //! on the `octave::symbol_table` and can be called by the
182 //! interpreter. Internally, the method name is prepended by an
183 //! `F`.
184 //! @param interp_name The name of the `octave::interpreter` reference that can
185 //! be used by this method. If this value is omitted,
186 //! there is no access to the interpreter and one should
187 //! use #DEFCONSTFUN to define a function instead.
188 //! @param args_name The name of the octave_value_list variable used to pass
189 //! the argument list to this method. If this value is
190 //! omitted, the method cannot access the argument list.
191 //! @param nargout_name The name of the `int` variable used to pass the number
192 //! of output arguments this method is expected to
193 //! produce from the caller. If this value is
194 //! omitted, the method cannot access this number.
195 //! @param doc Texinfo help text (docstring) for the method.
196 //!
197 //! @see DEFMETHOD, DEFMETHODX
66 198
67 #define DEFCONSTMETHOD(name, interp_name, args_name, nargout_name, doc) \ 199 #define DEFCONSTMETHOD(name, interp_name, args_name, nargout_name, doc) \
68 DECLARE_METHOD (name, interp_name, args_name, nargout_name) 200 DECLARE_METHOD (name, interp_name, args_name, nargout_name)
69 201
70 // Make alias another name for the existing function name. This macro 202 //! Macro to define an alias for another existing function name.
71 // is processed by the mkbuiltins to generate code in builtins.cc to 203 //!
72 // create the alias in the symbol table. 204 //! For detailed information, see \ref Macros.
205 //!
206 //! @param alias For another existing function name.
207 //! @param name The name of the other existing function.
208 //!
209 //! @see DEFUN
73 210
74 #define DEFALIAS(alias, name) 211 #define DEFALIAS(alias, name)
75 212
76 #endif 213 #endif