jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'vadz-doxygen'

Browse source 
This is the Doxygen work begun in Google Summer of Code projects 2008
and 2012 and subsequently improved by numerous contributors.

* vadz-doxygen: (314 commits)
  Add changes entry for Doxygen support
  Add some missing doctype tyemaps
  Doxygen warnings cleanup
  Move doxygen warning numbers
  Add Python doxygen example
  Doxygen example
  Add Doxygen to include paths
  Doxygen source rename
  More merge fixes from doxygen branches
  Correct python example headers
  Correct source code headers
  Another merge fix from doxygen branches
  Java enums output format fixes
  Add omitted doxygen_parsing_enums testcase
  PEP8 conformance for comment verifier module
  Clean up merge problem
  Doxygen html tweaks
  Update html chapter numbering for added Doxygen chapter
  Fixes to makechap.py to detect ill-formed headers
  html fixes for Doxygen
  Add missing CPlusPlus17.html file
  Format files to unix format
  Doxygen testcase tweak to match that in the html docs
  Doxygen html documentation updates and corrections
  Remove doxygen Examples subdirectory
  Beautify doxygen source code
  Code formatting fixes in doxygen code
  Remove unused doxygen code
  new_node refactor
  Various merge fixes in doxygen branches
  Unused variable warning fix
  Fix wrongly resetting indent after formulae in Doxygen comments
  Add support for doxygen:alias feature
  Get rid of meaningless return type of DoxygenParser methods
  Return enum, not untyped int, when classifying Doxygen commands
  Get rid of unnecessary "typedef enum" in C++ code
  Use slash, not backslash, in "C/C++" in the documentation
  Replace literal "<" with "&lt;" in HTML documentation
  Fix broken link to java.sun.com in Doxygen documentation
  Fix using com.sun.tools.javadoc package under macOS
  Fix error reporting for special characters in Doxygen parsing code
  Switch Python Doxygen unit tests to use inspect.getdoc()
  Use correct separator in Java class path under Windows.
  Remove executable permission from appveyor.yml.
  Use JAVA_HOME value in configure to detect Java.
  Display JAVA_HOME value in "make java_version".
  Fix harmless MSVC warning in DoxygenTranslator code.
  Reset "_last" for all but first enum elements.
  Don't duplicate Javadoc from global enum Doxygen comments twice.
  Move Doxygen comments concatenation from the parser to the lexer.
  Fix shift/reduce conflicts in Doxygen pre/post comment parsing.
  Rewrote part of the grammar dealing with Doxygen comments for enums.
  No changes, just remove spurious white space only differences.
  Move Doxygen comment mangling from the parser to the lexer.
  Merge "-builtin" autodoc bugs workarounds from master into test.
  Quote JAVA_HOME variable value in Java test suite makefile.
  Remove unused C_COMMENT_STRING terminal from the grammar.
  Fix missing returns in the Doxygen test suite code.
  Fix trimming whitespace from Doxygen comments.
  Remove code not doing anything from PyDocConverter.
  Remove unused <sstream> header.
  Remove unreferenced struct declaration.
  Remove unused Swig_warn() function.
  Remove any whitespace before ignored Doxygen commands.
  Remove trailing space from one of Doxygen tests.
  Fix autodoc strings generated in Python builtin case and the test.
  Fix Doxygen unit test in Python "-builtin" case.
  Use class docstrings in "-builtin" Python case.
  Don't indent Doxygen doc strings in generated Python code.
  Add a possibility to flexibly ignore custom Doxygen tags.
  Stop completely ignoring many Doxygen comments.
  Fix structural Doxygen comment recognition in the parser.
  No changes, just make checking for Doxygen structural tags more sane.
  Use "//", not "#", for comments in SWIG input.
  Allow upper case letters and digits in Doxygen words.
  Pass the node the Doxygen comment is attached to to DoxygenParser.
  Get rid of findCommand() which duplicaed commandBelongs().
  Recognize unknown Doxygen tags correctly.
  No real changes, just pass original command to commandBelongs().
  Describe Doxygen-specific %features in a single place.
  Give warnings for unknown Doxygen commands in Doxygen parser.
  Document the return type when translating Doxygen @return to Python.
  Fix translated Doxygen comments for overloaded functions in Python.
  Also merge Doxygen comments for overloaded constructors in Python.
  Allow using enum elements as default values for Python functions.
  Don't always use "*args" for all Python wrapper functions.
  No real changes, just make PYTHON::check_kwargs() const.
  Refactor: move makeParameterName() to common Language base class.
  Remove long line wrapping from Python parameter list generation code.
  Simplify and make more efficient building Python docstrings.
  Translate Doxygen code blocks to Sphinx code blocks.
  Add a simple test of multiple parameters to Doxygen test suite.
  Make Python parameters types hyperlinks in the doc strings.
  Make Language::classLookup() and enumLookup() static.
  Fix arguments of @param, @return etc translations to Python.
  Remove unused method from PyDocConverter.
  No real changes, just remove an unnecessary variable.
  Preserve relative indentation when parsing Doxygen comments.
  Use Sphinx-friendly formatting for overloaded functions documentation.
  Add poor man trailing white space detection to Doxygen Python tests.
  ...
This commit is contained in:
William S Fulton 2018-06-07 08:13:10 +01:00
commit 33921666a1
123 changed files with 12964 additions and 1344 deletions
Download patch file Download diff file Expand all files Collapse all files

90
Doc/Manual/Scilab.html
View file

@ -9,7 +9,7 @@
<body bgcolor="#ffffff">
<H1><a name="Scilab">40 SWIG and Scilab</a></H1>
<H1><a name="Scilab">41 SWIG and Scilab</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -88,7 +88,7 @@ This chapter explains how to use SWIG for Scilab. After this introduction, you s
</p>
<H2><a name="Scilab_preliminaries">40.1 Preliminaries</a></H2>
<H2><a name="Scilab_preliminaries">41.1 Preliminaries</a></H2>
<p>
@ -105,7 +105,7 @@ SWIG for Scilab supports C language. C++ is partially supported. See <a href="#S
</p>
<H2><a name="Scilab_running_swig">40.2 Running SWIG</a></H2>
<H2><a name="Scilab_running_swig">41.2 Running SWIG</a></H2>
<p>
@ -139,7 +139,7 @@ Note: a code in an <tt>%inline</tt> section is both parsed and wrapped by SWIG,
</p>
<H3><a name="Scilab_running_swig_generating_module">40.2.1 Generating the module</a></H3>
<H3><a name="Scilab_running_swig_generating_module">41.2.1 Generating the module</a></H3>
<p>
@ -182,7 +182,7 @@ The <tt>swig</tt> executable has several other command line options you can use.
</p>
<H3><a name="Scilab_running_swig_building_module">40.2.2 Building the module</a></H3>
<H3><a name="Scilab_running_swig_building_module">41.2.2 Building the module</a></H3>
<p>
@ -202,7 +202,7 @@ $ gcc -shared example_wrap.o -o libexample.so
Note: we supposed in this example that the path to the Scilab include directory is <tt>/usr/local/include/scilab</tt> (which is the case in a Debian environment), this should be changed for another environment.
</p>
<H3><a name="Scilab_running_swig_loading_module">40.2.3 Loading the module</a></H3>
<H3><a name="Scilab_running_swig_loading_module">41.2.3 Loading the module</a></H3>
<p>
@ -226,7 +226,7 @@ Link done.
which means that Scilab has successfully loaded the shared library. The module functions and other symbols are now available in Scilab.
</p>
<H3><a name="Scilab_running_swig_using_module">40.2.4 Using the module</a></H3>
<H3><a name="Scilab_running_swig_using_module">41.2.4 Using the module</a></H3>
<p>
@ -260,7 +260,7 @@ ans =
Note: for conciseness, we assume in the subsequent Scilab code examples that the modules have been beforehand built and loaded in Scilab.
</p>
<H3><a name="Scilab_running_swig_options">40.2.5 Scilab command line options</a></H3>
<H3><a name="Scilab_running_swig_options">41.2.5 Scilab command line options</a></H3>
<p>
@ -320,10 +320,10 @@ $ swig -scilab -help
</pre></div>
<H2><a name="Scilab_wrapping">40.3 A basic tour of C/C++ wrapping</a></H2>
<H2><a name="Scilab_wrapping">41.3 A basic tour of C/C++ wrapping</a></H2>
<H3><a name="Scilab_wrapping_overview">40.3.1 Overview</a></H3>
<H3><a name="Scilab_wrapping_overview">41.3.1 Overview</a></H3>
<p>
@ -332,7 +332,7 @@ This means that functions, structs, classes, variables, etc... are interfaced th
There are a few exceptions, such as constants and enumerations, which can be wrapped directly as Scilab variables.
</p>
<H3><a name="Scilab_wrapping_identifiers">40.3.2 Identifiers</a></H3>
<H3><a name="Scilab_wrapping_identifiers">41.3.2 Identifiers</a></H3>
<p>
@ -347,7 +347,7 @@ In these cases, the <a href="SWIG.html#SWIG_rename_ignore">%rename directive</a>
Note: truncations can be disabled by specifying the target version 6 of Scilab in the <tt>targetversion</tt> argument (i.e. <tt>-targetversion 6</tt>).
</p>
<H3><a name="Scilab_wrapping_functions">40.3.3 Functions</a></H3>
<H3><a name="Scilab_wrapping_functions">41.3.3 Functions</a></H3>
<p>
@ -378,7 +378,7 @@ ans =
24.
</pre></div>
<H4><a name="Scilab_nn13">40.3.3.1 Argument passing</a></H4>
<H4><a name="Scilab_nn13">41.3.3.1 Argument passing</a></H4>
<p>
@ -431,7 +431,7 @@ In Scilab, parameters are passed by value. The output (and inout) parameters are
7.
</pre></div>
<H4><a name="Scilab_nn14">40.3.3.2 Multiple output arguments</a></H4>
<H4><a name="Scilab_nn14">41.3.3.2 Multiple output arguments</a></H4>
<p>
@ -480,7 +480,7 @@ int divide(int n, int d, int *OUTPUT, int *OUTPUT);
</pre></div>
<H3><a name="Scilab_wrapping_global_variables">40.3.4 Global variables</a></H3>
<H3><a name="Scilab_wrapping_global_variables">41.3.4 Global variables</a></H3>
<p>
@ -549,10 +549,10 @@ It works the same:</p>
</pre></div>
<H3><a name="Scilab_wrapping_constants_and_enums">40.3.5 Constants and enumerations</a></H3>
<H3><a name="Scilab_wrapping_constants_and_enums">41.3.5 Constants and enumerations</a></H3>
<H4><a name="Scilab_wrapping_constants">40.3.5.1 Constants</a></H4>
<H4><a name="Scilab_wrapping_constants">41.3.5.1 Constants</a></H4>
<p>
@ -693,7 +693,7 @@ are mapped to Scilab variables, with the same name:
3.14
</pre></div>
<H4><a name="Scilab_wrapping_enums">40.3.5.2 Enumerations</a></H4>
<H4><a name="Scilab_wrapping_enums">41.3.5.2 Enumerations</a></H4>
<p>
@ -758,7 +758,7 @@ typedef enum { RED, BLUE, GREEN } color;
</pre></div>
<H3><a name="Scilab_wrapping_pointers">40.3.6 Pointers</a></H3>
<H3><a name="Scilab_wrapping_pointers">41.3.6 Pointers</a></H3>
<p>
@ -820,7 +820,7 @@ Note: the type name <tt>_p_FILE</tt> which means "pointer to FILE".
The user of a pointer is responsible for freeing it or, like in the example, closing any resources associated with it (just as is required in a C program).
</p>
<H4><a name="Scilab_wrapping_pointers_utility_functions">40.3.6.1 Utility functions</a></H4>
<H4><a name="Scilab_wrapping_pointers_utility_functions">41.3.6.1 Utility functions</a></H4>
<p>
@ -861,7 +861,7 @@ ans =
</pre></div>
<H4><a name="Scilab_wrapping_pointers_null_pointers">40.3.6.2 Null pointers:</a></H4>
<H4><a name="Scilab_wrapping_pointers_null_pointers">41.3.6.2 Null pointers:</a></H4>
<p>
@ -877,7 +877,7 @@ Using the previous <tt>SWIG_this()</tt> and <tt>SWIG_ptr()</tt>, it is possible
</pre></div>
<H3><a name="Scilab_wrapping_structs">40.3.7 Structures</a></H3>
<H3><a name="Scilab_wrapping_structs">41.3.7 Structures</a></H3>
<p>
@ -986,7 +986,7 @@ Note: the pointer to the struct works as described in <a href="Scilab_wrapping_p
--&gt; delete_Bar(b);
</pre></div>
<H3><a name="Scilab_wrapping_cpp_classes">40.3.8 C++ classes</a></H3>
<H3><a name="Scilab_wrapping_cpp_classes">41.3.8 C++ classes</a></H3>
<p>
@ -1054,7 +1054,7 @@ Note: like structs, class pointers are mapped as described in <a href="Scilab_wr
--&gt; delete_Point(p);
</pre></div>
<H3><a name="Scilab_wrapping_cpp_inheritance">40.3.9 C++ inheritance</a></H3>
<H3><a name="Scilab_wrapping_cpp_inheritance">41.3.9 C++ inheritance</a></H3>
<p>
@ -1129,7 +1129,7 @@ But we can use either use the <tt>get_perimeter()</tt> function of the parent cl
18.84
</pre></div>
<H3><a name="Scilab_wrapping_cpp_overloading">40.3.10 C++ overloading</a></H3>
<H3><a name="Scilab_wrapping_cpp_overloading">41.3.10 C++ overloading</a></H3>
<p>
@ -1169,7 +1169,7 @@ void magnify(Circle *circle, double factor) {
</pre></div>
<H3><a name="Scilab_wrapping_pointers_references_values_arrays">40.3.11 Pointers, references, values, and arrays</a></H3>
<H3><a name="Scilab_wrapping_pointers_references_values_arrays">41.3.11 Pointers, references, values, and arrays</a></H3>
<p>
@ -1227,7 +1227,7 @@ All these functions will return a pointer to an instance of <tt>Foo</tt>.
As the function <tt>spam7</tt> returns a value, new instance of <tt>Foo</tt> has to be allocated, and a pointer on this instance is returned.
</p>
<H3><a name="Scilab_wrapping_cpp_templates">40.3.12 C++ templates</a></H3>
<H3><a name="Scilab_wrapping_cpp_templates">41.3.12 C++ templates</a></H3>
<p>
@ -1286,7 +1286,7 @@ Then in Scilab:
More details on template support can be found in the <a href="SWIGPlus.html#SWIGPlus_nn30">templates</a> documentation.
</p>
<H3><a name="Scilab_wrapping_cpp_operators">40.3.13 C++ operators</a></H3>
<H3><a name="Scilab_wrapping_cpp_operators">41.3.13 C++ operators</a></H3>
<p>
@ -1339,7 +1339,7 @@ private:
</pre></div>
<H3><a name="Scilab_wrapping_cpp_namespaces">40.3.14 C++ namespaces</a></H3>
<H3><a name="Scilab_wrapping_cpp_namespaces">41.3.14 C++ namespaces</a></H3>
<p>
@ -1417,7 +1417,7 @@ Note: the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace</a> feature is not supp
</p>
<H3><a name="Scilab_wrapping_cpp_exceptions">40.3.15 C++ exceptions</a></H3>
<H3><a name="Scilab_wrapping_cpp_exceptions">41.3.15 C++ exceptions</a></H3>
<p>
@ -1500,17 +1500,17 @@ More complex or custom exception types require specific exception typemaps to be
See the <a href="SWIGPlus.html#SWIGPlus">SWIG C++ documentation</a> for more details.
</p>
<H3><a name="Scilab_wrapping_cpp_stl">40.3.16 C++ STL</a></H3>
<H3><a name="Scilab_wrapping_cpp_stl">41.3.16 C++ STL</a></H3>
<p>
The Standard Template Library (STL) is partially supported. See <a href="#Scilab_typemaps_stl">STL</a> for more details.
</p>
<H2><a name="Scilab_typemaps">40.4 Type mappings and libraries</a></H2>
<H2><a name="Scilab_typemaps">41.4 Type mappings and libraries</a></H2>
<H3><a name="Scilab_typemaps_primitive_types">40.4.1 Default primitive type mappings</a></H3>
<H3><a name="Scilab_typemaps_primitive_types">41.4.1 Default primitive type mappings</a></H3>
<p>
@ -1561,7 +1561,7 @@ The default behaviour is for SWIG to generate code that will give a runtime erro
<H3><a name="Scilab_typemaps_arrays">40.4.2 Arrays</a></H3>
<H3><a name="Scilab_typemaps_arrays">41.4.2 Arrays</a></H3>
<p>
@ -1616,7 +1616,7 @@ void printArray(int values[], int len) {
[ 0 1 2 3 ]
</pre></div>
<H3><a name="Scilab_typemaps_pointer-to-pointers">40.4.3 Pointer-to-pointers</a></H3>
<H3><a name="Scilab_typemaps_pointer-to-pointers">41.4.3 Pointer-to-pointers</a></H3>
<p>
@ -1689,7 +1689,7 @@ void print_matrix(double **M, int nbRows, int nbCols) {
</pre></div>
<H3><a name="Scilab_typemaps_matrices">40.4.4 Matrices</a></H3>
<H3><a name="Scilab_typemaps_matrices">41.4.4 Matrices</a></H3>
<p>
@ -1782,7 +1782,7 @@ The remarks made earlier for arrays also apply here:
<li>There is no control while converting <tt>double</tt> values to integers, <tt>double</tt> values are truncated without any checking or warning.</li>
</ul>
<H3><a name="Scilab_typemaps_stl">40.4.5 STL</a></H3>
<H3><a name="Scilab_typemaps_stl">41.4.5 STL</a></H3>
<p>
@ -1982,7 +1982,7 @@ ans =
--&gt; delete_PersonPtrSet(p);
</pre></div>
<H2><a name="Scilab_module_initialization">40.5 Module initialization</a></H2>
<H2><a name="Scilab_module_initialization">41.5 Module initialization</a></H2>
<p>
@ -2006,7 +2006,7 @@ For example, to initialize the module <tt>example</tt>:
--&gt; example_Init();
</pre></div>
<H2><a name="Scilab_building_modes">40.6 Building modes</a></H2>
<H2><a name="Scilab_building_modes">41.6 Building modes</a></H2>
<p>
@ -2021,7 +2021,7 @@ To produce a dynamic module, when generating the wrapper, there are two possibil
<li>the <tt>builder</tt> mode. In this mode, Scilab is responsible of building.
</ul>
<H3><a name="Scilab_building_modes_nobuilder_mode">40.6.1 No-builder mode</a></H3>
<H3><a name="Scilab_building_modes_nobuilder_mode">41.6.1 No-builder mode</a></H3>
<p>
@ -2034,7 +2034,7 @@ This mode is the best option to use when you have to integrate the module build
</p>
<H3><a name="Scilab_building_modes_builder_mode">40.6.2 Builder mode</a></H3>
<H3><a name="Scilab_building_modes_builder_mode">41.6.2 Builder mode</a></H3>
<p>
@ -2074,14 +2074,14 @@ The command is:
$ swig -scilab -builder -buildercflags -I/opt/foo/include -builderldflags "-L/opt/foo/lib -lfoo" -buildersources baa1.cxx, baa2.cxx example.i
</pre></div>
<H2><a name="Scilab_generated_scripts">40.7 Generated scripts</a></H2>
<H2><a name="Scilab_generated_scripts">41.7 Generated scripts</a></H2>
<p>
In this part we give some details about the generated Scilab scripts.
</p>
<H3><a name="Scilab_generated_scripts_builder_script">40.7.1 Builder script</a></H3>
<H3><a name="Scilab_generated_scripts_builder_script">41.7.1 Builder script</a></H3>
<p>
@ -2106,7 +2106,7 @@ ilib_build(ilib_name, table, files, libs);
<li><tt><b>table</b></tt>: two column string matrix containing a table of pairs of 'scilab function name', 'C function name'.</li>
</ul>
<H3><a name="Scilab_generated_scripts_loader_script">40.7.2 Loader script</a></H3>
<H3><a name="Scilab_generated_scripts_loader_script">41.7.2 Loader script</a></H3>
<p>
@ -2145,7 +2145,7 @@ clear get_file_path;
</ul>
<H2><a name="Scilab_other_resources">40.8 Other resources</a></H2>
<H2><a name="Scilab_other_resources">41.8 Other resources</a></H2>
<ul>