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

100
Doc/Manual/Extending.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Extending">42 Extending SWIG to support new languages</a></H1>
<H1><a name="Extending">43 Extending SWIG to support new languages</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -76,7 +76,7 @@
<H2><a name="Extending_nn2">42.1 Introduction</a></H2>
<H2><a name="Extending_nn2">43.1 Introduction</a></H2>
<p>
@ -92,7 +92,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po
you should probably look at one of SWIG's existing modules.
</p>
<H2><a name="Extending_nn3">42.2 Prerequisites</a></H2>
<H2><a name="Extending_nn3">43.2 Prerequisites</a></H2>
<p>
@ -122,7 +122,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of
wrapper code are driven by C++ datatypes.
</p>
<H2><a name="Extending_nn4">42.3 The Big Picture</a></H2>
<H2><a name="Extending_nn4">43.3 The Big Picture</a></H2>
<p>
@ -159,7 +159,7 @@ role in making the system work. For example, both typemaps and declaration anno
based on pattern matching and interact heavily with the underlying type system.
</p>
<H2><a name="Extending_nn5">42.4 Execution Model</a></H2>
<H2><a name="Extending_nn5">43.4 Execution Model</a></H2>
<p>
@ -204,7 +204,7 @@ latter stage of compilation.
The next few sections briefly describe some of these stages.
</p>
<H3><a name="Extending_nn6">42.4.1 Preprocessing</a></H3>
<H3><a name="Extending_nn6">43.4.1 Preprocessing</a></H3>
<p>
@ -285,7 +285,7 @@ been expanded as well as everything else that goes into the low-level
construction of the wrapper code.
</p>
<H3><a name="Extending_nn7">42.4.2 Parsing</a></H3>
<H3><a name="Extending_nn7">43.4.2 Parsing</a></H3>
<p>
@ -386,7 +386,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
arguments).
</p>
<H3><a name="Extending_nn8">42.4.3 Parse Trees</a></H3>
<H3><a name="Extending_nn8">43.4.3 Parse Trees</a></H3>
<p>
@ -641,7 +641,7 @@ $ swig -c++ -python -debug-module 4 example.i
</pre>
</div>
<H3><a name="Extending_nn9">42.4.4 Attribute namespaces</a></H3>
<H3><a name="Extending_nn9">43.4.4 Attribute namespaces</a></H3>
<p>
@ -660,7 +660,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt>
<tt>perl:foo</tt>.
</p>
<H3><a name="Extending_nn10">42.4.5 Symbol Tables</a></H3>
<H3><a name="Extending_nn10">43.4.5 Symbol Tables</a></H3>
<p>
@ -751,7 +751,7 @@ example.i:5. Previous declaration is foo_i(int )
</pre>
</div>
<H3><a name="Extending_nn11">42.4.6 The %feature directive</a></H3>
<H3><a name="Extending_nn11">43.4.6 The %feature directive</a></H3>
<p>
@ -807,7 +807,7 @@ For example, the exception code above is simply
stored without any modifications.
</p>
<H3><a name="Extending_nn12">42.4.7 Code Generation</a></H3>
<H3><a name="Extending_nn12">43.4.7 Code Generation</a></H3>
<p>
@ -929,7 +929,7 @@ public :
The role of these functions is described shortly.
</p>
<H3><a name="Extending_nn13">42.4.8 SWIG and XML</a></H3>
<H3><a name="Extending_nn13">43.4.8 SWIG and XML</a></H3>
<p>
@ -942,7 +942,7 @@ internal data structures, it may be useful to keep XML in the back of
your mind as a model.
</p>
<H2><a name="Extending_nn14">42.5 Primitive Data Structures</a></H2>
<H2><a name="Extending_nn14">43.5 Primitive Data Structures</a></H2>
<p>
@ -988,7 +988,7 @@ typedef Hash Typetab;
</pre>
</div>
<H3><a name="Extending_nn15">42.5.1 Strings</a></H3>
<H3><a name="Extending_nn15">43.5.1 Strings</a></H3>
<p>
@ -1129,7 +1129,7 @@ Returns the number of replacements made (if any).
</div>
<H3><a name="Extending_nn16">42.5.2 Hashes</a></H3>
<H3><a name="Extending_nn16">43.5.2 Hashes</a></H3>
<p>
@ -1206,7 +1206,7 @@ Returns the list of hash table keys.
</div>
<H3><a name="Extending_nn17">42.5.3 Lists</a></H3>
<H3><a name="Extending_nn17">43.5.3 Lists</a></H3>
<p>
@ -1295,7 +1295,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
and is used to create a String object.
</div>
<H3><a name="Extending_nn18">42.5.4 Common operations</a></H3>
<H3><a name="Extending_nn18">43.5.4 Common operations</a></H3>
The following operations are applicable to all datatypes.
@ -1350,7 +1350,7 @@ objects and report errors.
Gets the line number associated with <tt>x</tt>.
</div>
<H3><a name="Extending_nn19">42.5.5 Iterating over Lists and Hashes</a></H3>
<H3><a name="Extending_nn19">43.5.5 Iterating over Lists and Hashes</a></H3>
To iterate over the elements of a list or a hash table, the following functions are used:
@ -1395,7 +1395,7 @@ for (j = First(j); j.item; j= Next(j)) {
</div>
<H3><a name="Extending_nn20">42.5.6 I/O</a></H3>
<H3><a name="Extending_nn20">43.5.6 I/O</a></H3>
Special I/O functions are used for all internal I/O. These operations
@ -1529,7 +1529,7 @@ Printf(f, "%s\n", s);
Similarly, the preprocessor and parser all operate on string-files.
</p>
<H2><a name="Extending_nn21">42.6 Navigating and manipulating parse trees</a></H2>
<H2><a name="Extending_nn21">43.6 Navigating and manipulating parse trees</a></H2>
Parse trees are built as collections of hash tables. Each node is a hash table in which
@ -1663,7 +1663,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u
the parent so that sibling nodes are unaffected.
</div>
<H2><a name="Extending_nn22">42.7 Working with attributes</a></H2>
<H2><a name="Extending_nn22">43.7 Working with attributes</a></H2>
<p>
@ -1780,7 +1780,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after
function.
</div>
<H2><a name="Extending_nn23">42.8 Type system</a></H2>
<H2><a name="Extending_nn23">43.8 Type system</a></H2>
<p>
@ -1789,7 +1789,7 @@ pointers, references, and pointers to members. A detailed discussion of
type theory is impossible here. However, let's cover the highlights.
</p>
<H3><a name="Extending_nn24">42.8.1 String encoding of types</a></H3>
<H3><a name="Extending_nn24">43.8.1 String encoding of types</a></H3>
<p>
@ -1890,7 +1890,7 @@ make the final type, the two parts are just joined together using
string concatenation.
</p>
<H3><a name="Extending_nn25">42.8.2 Type construction</a></H3>
<H3><a name="Extending_nn25">43.8.2 Type construction</a></H3>
<p>
@ -2059,7 +2059,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
<tt>ty</tt> is unmodified.
</div>
<H3><a name="Extending_nn26">42.8.3 Type tests</a></H3>
<H3><a name="Extending_nn26">43.8.3 Type tests</a></H3>
<p>
@ -2146,7 +2146,7 @@ Checks if <tt>ty</tt> is a varargs type.
Checks if <tt>ty</tt> is a templatized type.
</div>
<H3><a name="Extending_nn27">42.8.4 Typedef and inheritance</a></H3>
<H3><a name="Extending_nn27">43.8.4 Typedef and inheritance</a></H3>
<p>
@ -2248,7 +2248,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
will consist only of primitive typenames.
</div>
<H3><a name="Extending_nn28">42.8.5 Lvalues</a></H3>
<H3><a name="Extending_nn28">43.8.5 Lvalues</a></H3>
<p>
@ -2285,7 +2285,7 @@ Literal y; // type = 'Literal', ltype='p.char'
</pre>
</div>
<H3><a name="Extending_nn29">42.8.6 Output functions</a></H3>
<H3><a name="Extending_nn29">43.8.6 Output functions</a></H3>
<p>
@ -2347,7 +2347,7 @@ SWIG, but is most commonly associated with type-descriptor objects
that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
</div>
<H2><a name="Extending_nn30">42.9 Parameters</a></H2>
<H2><a name="Extending_nn30">43.9 Parameters</a></H2>
<p>
@ -2446,7 +2446,7 @@ included. Used to emit prototypes.
Returns the number of required (non-optional) arguments in <tt>p</tt>.
</div>
<H2><a name="Extending_nn31">42.10 Writing a Language Module</a></H2>
<H2><a name="Extending_nn31">43.10 Writing a Language Module</a></H2>
<p>
@ -2461,7 +2461,7 @@ describes the creation of a minimal Python module. You should be able to extra
this to other languages.
</p>
<H3><a name="Extending_nn32">42.10.1 Execution model</a></H3>
<H3><a name="Extending_nn32">43.10.1 Execution model</a></H3>
<p>
@ -2471,7 +2471,7 @@ the parsing of command line options, all aspects of code generation are controll
different methods of the <tt>Language</tt> that must be defined by your module.
</p>
<H3><a name="Extending_starting_out">42.10.2 Starting out</a></H3>
<H3><a name="Extending_starting_out">43.10.2 Starting out</a></H3>
<p>
@ -2579,7 +2579,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The
messages from your new module should appear.
</p>
<H3><a name="Extending_nn34">42.10.3 Command line options</a></H3>
<H3><a name="Extending_nn34">43.10.3 Command line options</a></H3>
<p>
@ -2638,7 +2638,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit
unrecognized command line option error.
</p>
<H3><a name="Extending_nn35">42.10.4 Configuration and preprocessing</a></H3>
<H3><a name="Extending_nn35">43.10.4 Configuration and preprocessing</a></H3>
<p>
@ -2687,7 +2687,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file
<tt>python.swg</tt>.
</p>
<H3><a name="Extending_nn36">42.10.5 Entry point to code generation</a></H3>
<H3><a name="Extending_nn36">43.10.5 Entry point to code generation</a></H3>
<p>
@ -2745,7 +2745,7 @@ int Python::top(Node *n) {
</pre>
</div>
<H3><a name="Extending_nn37">42.10.6 Module I/O and wrapper skeleton</a></H3>
<H3><a name="Extending_nn37">43.10.6 Module I/O and wrapper skeleton</a></H3>
<!-- please report bugs in this section to mgossage -->
@ -2893,7 +2893,7 @@ functionWrapper : void Shape_y_set(Shape *self, double y)
</pre>
</div>
<H3><a name="Extending_nn38">42.10.7 Low-level code generators</a></H3>
<H3><a name="Extending_nn38">43.10.7 Low-level code generators</a></H3>
<!-- please report bugs in this section to mgossage -->
@ -3047,7 +3047,7 @@ but without the typemaps, there is still work to do.
</p>
<H3><a name="Extending_configuration_files">42.10.8 Configuration files</a></H3>
<H3><a name="Extending_configuration_files">43.10.8 Configuration files</a></H3>
<!-- please report bugs in this section to ttn -->
@ -3191,7 +3191,7 @@ politely displays the ignoring language message.
</dl>
<H3><a name="Extending_nn40">42.10.9 Runtime support</a></H3>
<H3><a name="Extending_nn40">43.10.9 Runtime support</a></H3>
<p>
@ -3200,7 +3200,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
the SWIG files that implement those functions.
</p>
<H3><a name="Extending_nn41">42.10.10 Standard library files</a></H3>
<H3><a name="Extending_nn41">43.10.10 Standard library files</a></H3>
<p>
@ -3219,7 +3219,7 @@ The following are the minimum that are usually supported:
Please copy these and modify for any new language.
</p>
<H3><a name="Extending_nn42">42.10.11 User examples</a></H3>
<H3><a name="Extending_nn42">43.10.11 User examples</a></H3>
<p>
@ -3248,7 +3248,7 @@ during this process, see the section on <a href="#Extending_configuration_files"
files</a>.
</p>
<H3><a name="Extending_test_suite">42.10.12 Test driven development and the test-suite</a></H3>
<H3><a name="Extending_test_suite">43.10.12 Test driven development and the test-suite</a></H3>
<p>
@ -3307,7 +3307,7 @@ It is therefore essential that the runtime tests are written in a manner that di
but error/exception out with an error message on stderr on failure.
</p>
<H4><a name="Extending_running_test_suite">42.10.12.1 Running the test-suite</a></H4>
<H4><a name="Extending_running_test_suite">43.10.12.1 Running the test-suite</a></H4>
<p>
@ -3499,7 +3499,7 @@ It can be run in the same way as the other language test-suites, replacing [lang
The test cases used and the way it works is described in <tt>Examples/test-suite/errors/Makefile.in</tt>.
</p>
<H3><a name="Extending_nn43">42.10.13 Documentation</a></H3>
<H3><a name="Extending_nn43">43.10.13 Documentation</a></H3>
<p>
@ -3531,7 +3531,7 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<H3><a name="Extending_prerequisites">42.10.14 Prerequisites for adding a new language module to the SWIG distribution</a></H3>
<H3><a name="Extending_prerequisites">43.10.14 Prerequisites for adding a new language module to the SWIG distribution</a></H3>
<p>
@ -3588,7 +3588,7 @@ should be added should there be an area not already covered by
the existing tests.
</p>
<H3><a name="Extending_coding_style_guidelines">42.10.15 Coding style guidelines</a></H3>
<H3><a name="Extending_coding_style_guidelines">43.10.15 Coding style guidelines</a></H3>
<p>
@ -3612,7 +3612,7 @@ The generated C/C++ code should also follow this style as close as possible. How
should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
</p>
<H2><a name="Extending_debugging_options">42.11 Debugging Options</a></H2>
<H2><a name="Extending_debugging_options">43.11 Debugging Options</a></H2>
<p>
@ -3639,7 +3639,7 @@ There are various command line options which can aid debugging a SWIG interface
The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
</p>
<H2><a name="Extending_nn46">42.12 Guide to parse tree nodes</a></H2>
<H2><a name="Extending_nn46">43.12 Guide to parse tree nodes</a></H2>
<p>
@ -4047,7 +4047,7 @@ extern "X" { ... } declaration.
</pre>
</div>
<H2><a name="Extending_further_info">42.13 Further Development Information</a></H2>
<H2><a name="Extending_further_info">43.13 Further Development Information</a></H2>
<p>