# HG changeset patch # User Kai T. Ohlhus # Date 1509720242 -3600 # Node ID b7e5486e7bff80c560ffb9372c414dfae0306c61 # Parent d5c38fdf77f93a307f5368c7c8655c28a7045e60 doc: Doxygen documentation with more descriptive pages. * doc/doxyhtml/Doxyfile.in: remove inclusion of README.md (renamed back to README in cset 3dbd6409eeb9), add "pages" directories of source and build directory, the latter one for generated pages (see module.mk). * doc/doxyhtml/module.mk: add static and dynamically generated Doxygen pages. New target to create README.md from README (this improves the usage in Doxygen by being able to specify the headline). * etc/HACKING.md: Make content trackable to Doxygen by adding a link label. * doc/doxyhtml/pages/macros.dox: add static page for Macro description. diff -r d5c38fdf77f9 -r b7e5486e7bff doc/doxyhtml/Doxyfile.in --- a/doc/doxyhtml/Doxyfile.in Wed Nov 01 14:05:56 2017 -0700 +++ b/doc/doxyhtml/Doxyfile.in Fri Nov 03 15:44:02 2017 +0100 @@ -374,12 +374,13 @@ # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = @abs_top_srcdir@/README.md \ - @abs_top_srcdir@/etc/HACKING.md \ - @abs_top_srcdir@/src/ \ +INPUT = @abs_top_srcdir@/src/ \ @abs_top_srcdir@/liboctave/ \ @abs_top_srcdir@/libinterp \ - @abs_top_srcdir@/libgui + @abs_top_srcdir@/libgui \ + @abs_top_srcdir@/etc/HACKING.md \ + @abs_top_srcdir@/doc/doxyhtml/pages \ + @abs_top_builddir@/doc/doxyhtml/pages # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff -r d5c38fdf77f9 -r b7e5486e7bff doc/doxyhtml/module.mk --- a/doc/doxyhtml/module.mk Wed Nov 01 14:05:56 2017 -0700 +++ b/doc/doxyhtml/module.mk Fri Nov 03 15:44:02 2017 +0100 @@ -1,11 +1,22 @@ -doxyhtml: %reldir%/Doxyfile | %reldir%/$(octave_dirstamp) +# Generate README.md from README and replace first line by a Doxygen +# specific one. +%reldir%/pages/README.md: $(srcdir)/README + $(MKDIR_P) $(@D) + cat $< | $(SED) '1s/.*/notitle {#mainpage}/; 2s/.*/=======/' > $@ + +DOXYGEN_PAGES = \ + %reldir%/pages/macros.dox \ + %reldir%/pages/README.md + +doxyhtml: %reldir%/Doxyfile $(DOXYGEN_PAGES) | %reldir%/$(octave_dirstamp) doxygen %reldir%/Doxyfile doxyhtml-maintainer-clean: rm -f doc/doxygen_sqlite3.db - rm -rf `ls -d %reldir%/* 2>/dev/null | $(GREP) -v 'Doxyfile\.in\|README'` + rm -rf `ls -d %reldir%/* 2>/dev/null | $(GREP) -v 'Doxyfile\.in\|README\|pages$'` doc_EXTRA_DIST += \ + $(DOXYGEN_PAGES) \ %reldir%/Doxyfile.in \ %reldir%/README diff -r d5c38fdf77f9 -r b7e5486e7bff doc/doxyhtml/pages/macros.dox --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/doxyhtml/pages/macros.dox Fri Nov 03 15:44:02 2017 +0100 @@ -0,0 +1,106 @@ +/** @page Macros Important Macros + +@tableofcontents + +Builtin function and method definition {#macros_defun} +====================================== + +In Octave a function is called from the interpreter by for example + + [a, b, c] = foo (d, e); + +If `foo` should be defined as **builtin function**, it has to have the type +`octave_builtin::fcn` or equivalently: + +```{.cc} +octave_value_list +Ffoo (const octave_value_list& args_name, int nargout_name) +``` + +> Notice the **F** prefix of `foo`! + +Basically, an `octave_value_list` goes in (referenced within that function by +`args_name`) and another `octave_value_list` comes out. The integer +`nargout_name` indicates, how many outputs arguments the caller of this +functions expects. + +Thus in the example above, `d` and `e` are available via `args_name` and +`nargout_name` takes the value `3`, because three output arguments `a`, `b`, +and `c` are expected. + +Very similar to builtin functions are **builtin methods**. Builtin methods +have to have the type `octave_builtin::meth` or equivalently: + +```{.cc} +octave_value_list +Ffoo (octave::interpreter& interp_name, + const octave_value_list& args_name, int nargout_name) +``` + +Notice again the `F` prefix of `foo`. + +> The difference between builtin functions and builtin methods is, that builtin +> methods have access to the `octave::interpreter`, which is referenced by +> `interp_name`. + +To make a builtin function or builtin method available to the interpreter, it +is not sufficient to just define them somewhere inside `libinterp`. Octave +provides two convenience macros, to define them properly: + +```{.cc} +DEFUN (foo, args_name, nargout_name, doc) +DEFMETHOD (foo, interp_name, args_name, nargout_name, doc) +``` + +> For a usage example, see the definition of `#Feig`. + +The last argument of both macros `doc` will not appear in the builtin function +or builtin method definition but is further processed. The idea is, that code +and documentation should be at one place. + +The macros #DEFUN or #DEFMETHOD fulfill two tasks: + +1. Proper builtin function or builtin method definition. +2. Defining a fixed pattern for further processing by + - `mk-builtins.pl` (installation on `octave::symbol_table`) + - `mk-doc.pl` (docstring `doc` extraction for the help system) + +In addition to #DEFUN and #DEFMETHOD, there are two specialized versions of +both macros, that should only be used with reason: + +1. If the name `foo` cannot be used directly (for example if it is already + defined as a macro), one can use instead one of + ```{.cc} + DEFUNX ("foo", Ffoo, args_name, nargout_name, doc) + DEFMETHODX ("foo", Ffoo, interp_name, args_name, nargout_name, doc) + ``` + where `"foo"` is the name for the interpreter, protected by macro expansion + inside a string, and `Ffoo` is the actual builtin function or builtin method + name. +2. In case `foo` may not be hidden by a variable, defined in an Octave + interpreter session, one can use instead one of + ```{.cc} + DEFCONSTFUN (foo, args_name, nargout_name, doc) + DEFCONSTMETHOD (foo, interp_name, args_name, nargout_name, doc) + ``` + +Last but not least, there is #DEFALIAS. As the name suggests, this macro can +be used to define an alias for an existing builtin function. + +Dynamic builtin function and method definition {#macros_defun_dld} +============================================== + +When making use of the [OCT-file interface][OCT], it is desired to define +functions or methods, than can be loaded dynamically at run time, e.g. those +are not loaded at Octave startup. + +[OCT]: https://www.gnu.org/software/octave/doc/interpreter/Oct_002dFiles.html + +To achieve this, analog to #DEFUN and #DEFMETHOD, there are: + +```{.cc} +DEFUN_DLD (name, args_name, nargout_name, doc) +DEFMETHOD_DLD (name, interp_name, args_name, nargout_name, doc) +``` + +**/ diff -r d5c38fdf77f9 -r b7e5486e7bff etc/HACKING.md --- a/etc/HACKING.md Wed Nov 01 14:05:56 2017 -0700 +++ b/etc/HACKING.md Fri Nov 03 15:44:02 2017 +0100 @@ -1,4 +1,4 @@ -Hacking Octave +Hacking Octave {#Hacking} ============== This file attempts to describe the rules to use when hacking the