Merge branch 'vadz-doxygen'

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.
  ...

1 files changed, 341 insertions, 0 deletions

diff --git a/Doc/Devel/plan-gsoc-2012.txt b/Doc/Devel/plan-gsoc-2012.txt
new file mode 100644
index 000000000..ac764fb2a
--- /dev/null
+++ b/Doc/Devel/plan-gsoc-2012.txt
@@ -0,0 +1,341 @@
+                                                                     
+                                                                     
+                                                                     
+                                             
+                   Project Plan
+                   ============
+                SWIG Code Comments
+             Google Summer of Code 2012
+
+
+This document describes goals for the Google Summer of Code 2012,
+SWIG code documentation project.
+
+Author: Marko Klopcic, Dmitry Kabak
+
+
+Introduction
+============
+
+The goal of this project is _not_ to translate _any_ possible Doxygen
+formatted comment to JavaDoc or PyDoc, but to make it possible to
+translate a subset of comment types in C/C++ code to
+JavaDoc and PyDoc. Covering all the Doxygen functionality would be to
+complex for the limited time. However, the code must be flexible so
+that implementing missing features would not require redesign of the
+comment handling code in SWIG.
+
+There will also be a possibility to add untranslated comments to Java
+and Python code (## comments, see Doxygen manual), if the user will
+prefer to use Doxygen on the generated code.
+
+Note:
+'-OK-' tick below means that the item is implemented, committed and
+working.
+
+Abbreviations:
+    JD - JavaDoc
+    PD - PyDoc
+
+
+Functionality
+=============
+
+  Types of comments
+  -----------------
+  
+  Note:
+     See 'http://www.stack.nl/~dimitri/doxygen/docblocks.html' for
+     the detailed description of Doxygen syntax and terms used in this
+     section.
+
+  1. -OK- Only JavaDoc (/** */) and Qt (/*! */) styles of comment blocks
+     will be supported by SWIG translator.
+
+  2. -OK- The following doc after members will be supported:
+  
+     int var; ///< Detailed description after the member
+              //!< 
+
+     int var; //!< Brief description after the member
+
+     int var; ///< Brief description after the member
+     
+
+  3. -OK- Only comments before or after declaration/definition will be
+     supported. Comments with structural commands will be ignored
+     (warning will be written). (What about writing them to
+     'package.info.java' for JD?)
+  
+
+  Tags
+  ----
+
+  This section contains all doxygen tags taken from 
+  http://www.stack.nl/~dimitri/doxygen/commands.html. If a tag is
+  marked as 'ignored', then the tag is ignored, but the text is copied
+  to the destination documentation. 'Not implemented' means that the
+  tag with it's contents is stripped out of the output.
+
+    Doxygen tags:
+    
+    All tags: -OK-     
+
+    \a - translated to <i></i> in JD, surrounded with _ in PD
+    \addindex - ignored
+    \addtogroup - ignored
+    \anchor - ignored, not supported by JD and PD 
+    \arg - equivalent to \li
+    \attention - ignored
+    \authors, \author - translated to @author in JD, 'Author:' in PD
+    \b - <b></b> in JD, surrounded with __ in PD
+    \brief - ignored
+    \bug - ignored
+    \c - translated to <code></code> in JD, ignored in PD
+    \callgraph - ignored, not supported by JD and PD
+    \callergraph - ignored, not supported by JD and PD
+    \category - ignored, used only in Objective C
+    \cite - translated to <i></i> in JD, single quotes in PD
+    \class - ignored (structural command)
+    \code - translated to {@code ...} in JD, ignored in PD
+    \cond - translated to 'Conditional comment: <condition>'. Later
+            SWIG may support definitions of conditions in config file.
+    \copybrief - ignored. Later SWIG may support this command by
+                  performing copy
+    \copydetails - ignored. Later SWIG may support this command by
+                   performing copy
+    \copydoc - ignored. Later SWIG may support this command by
+               performing copy
+    \copyright - replaced with text 'Copyright' in PD and PD
+    \date - ignored
+    \def - ignored (structural command)
+    \defgroup - not supported
+    \deprecated - translated to @deprecated in JD, 'Deprecated:' in PD
+    \details - ignored
+    \dir - not supported
+    \dontinclude - not supported
+    \dot - not supported. Later SWIG may call dot and produce the graph image
+           to include in JD and PD
+    \dotfile - see note for \dot
+    \e - equivalent \a
+    \else - see note for \cond
+    \elseif - see note for \cond
+    \em - equivalent to \a
+    \endcode - see note for \code
+    \endcond - translated to 'End of conditional comment: <condition>'. Later
+               SWIG may support definitions of conditions in config file.
+    \enddot - see note for \dot
+    \endhtmlonly - ignored
+    \endif - see note for \cond
+    \endinternal - ignored
+    \endlatexonly - ignored
+    \endlink - see note for \link
+    \endmanonly - ignored
+    \endmsc - see note for \msc
+    \endrtfonly - ignored
+    \endverbatim - see note for \verbatim
+    \endxmlonly - ignored
+    \enum - ignored (structural command)
+    \example - translated to 'Example:' in JD and PD
+    \exception - equivalent to throws, but translates to @exception in JD 
+    \extends - not supported
+    \f$ - ignored. Later swig may call LATeX to produce bitmaps with formulas
+          to include in JD and PD
+    \f[ - see note for \f$
+    \f] - see note for \f$
+    \f{ - see note for \f$
+    \f} - see note for \f$
+    \file - ignored (structural command)
+    \fn - ignored (structural command)
+    \headerfile - not supported
+    \hideinitializer - not supported
+    \htmlinclude - not supported
+    \htmlonly - ignored
+    \if - see note for \cond 
+    \ifnot - see note for \cond
+    \image - translated to <img/> in JD only when target=HTML, translated to
+             'Image: filename(Title)'
+    \implements - not supported
+    \include - not supported
+    \includelineno - not supported
+    \ingroup - not supported. Later swig may print group names as plain text
+               in comments like 'Code group: something' in both JD and PD
+    \internal - ignored
+    \invariant - ignored
+    \interface - ignored (structural command)
+    \latexonly - ignored
+    \li - trabslated to <li></li> in JD, ignored in PD
+    \line - not supported
+    \link - translated to {@link ...} in JD, ignored in PD
+    \mainpage - ignored
+    \manonly - ignored
+    \memberof - not supported
+    \msc - not supported. Later SWIG may call dot and produce the graph image
+           to include in JD and PD
+    \mscfile - see note for \msc
+    \n - prints the new line
+    \name - ignored
+    \namespace - included in package-info.java if nspace feature is enabled,
+                 otherwise ignored, ignored in PD
+    \nosubgrouping - ignored
+    \note - translated to 'Note:' in both JD and PD
+    \overload - prints 'This is an overloaded member function, provided for
+                convenience. It differs from the above function only in what
+                argument(s) it accepts.' to the output in both JD and PD
+    \p - equivalent to \c
+    \package - is kept same in JD (it is already a JD tag), ignored in PD
+    \page - ignored
+    \par - translated to <p alt='title'></p> in JD, 'Title: ...' in PD 
+    \paragraph - ignored
+    \param - translated to @param in JD, special formatting in PD
+    \post - ignored
+    \pre - ignored
+    \private - ignored
+    \privatesection - ignored
+    \property - ignored
+    \protected - ignored
+    \protectedsection - ignored
+    \protocol - ignored (Objective-C tag)
+    \public - ignored
+    \publicsection - ignored
+    \ref - ignored, not supported by JD and PD
+    \related - ignored 
+    \relates - ignored
+    \relatedalso - ignored
+    \relatesalso - ignored
+    \remark - translated to 'Remarks:' in both JD and PD
+    \remarks - equivalent to remark
+    \result - translated to @return in JD, 'Return:' in PD
+    \return - equivalent to result
+    \returns - equivalent to result
+    \retval - ignored
+    \rtfonly - ignored
+    \sa - translated to @see in JD, 'See also:' in PD
+    \section - not supported
+    \see - equivalent to \sa
+    \short - equivalent to \brief
+    \showinitializer - not supported
+    \since - translated to @since in JD, 'Since:' in PD
+    \skip - not supported
+    \skipline - not supported
+    \snippet - not supported
+    \struct - ignored (structural command)
+    \subpage - not supported
+    \subsection - not supported
+    \subsubsection - not supported
+    \tableofcontents - not supported
+    \test - ignored
+    \throw - translated to @throws in JD, 'Throws:' in PD 
+    \throws - equivalent to \throw
+    \todo - translated to 'TODO:' in both JD and PD
+    \tparam - similar to \arg
+    \typedef - ignored (structural command)
+    \union - ignored (structural command)
+    \until - not supported
+    \var - ignored (structural command)
+    \verbatim - translated to {@literal ...} in JD, ignored in PD
+    \verbinclude - ignored
+    \version - translated to @version in JD, 'Version:' in PD
+    \warning - translated to 'Warning:' in both JD and PD
+    \weakgroup - not supported
+    \xmlonly - ignored
+    \xrefitem - ignored
+    \$ - this and all the others below: these commands insert single char,
+         it is escaped as HTML char in JD, kept as-is in PD
+    \@
+    \\
+    \&
+    \~
+    \<
+    \>
+    \#
+    \%
+    \"
+    \.
+    \::
+
+Optional functionality
+======================
+
+That section describes some complex cases where the current code
+does not behave really well. Like a short to-do list of special cases.
+
+-OK- When translating functions with default parameters in swig to
+java, it creates overloaded functions with all the parameters
+except the default ones. We need to copy the doxygen comment to
+such functions and correct the list of @param tags.
+
+-OK- In doxygen there is a special tags (and even a special option)
+to create links to some code members from the current comment.
+Sometimes it needs a type of parameters specified because of the
+overloaded functions. And the same linking tags are supported in JD,
+but it has a completely different typesystem, so we need to translate
+the types of function parameters in comments also. For example:
+{@link MyClass#doSomething(const std::string &)}
+does not make sense in Java, so the type should be converted.
+{@link MyClass#doSomething(String)}
+ 
+    
+Tests
+=====
+
+The following test cases will be implemented:
+
+-OK- Class comments.
+
+-OK- Struct comments.
+-OK- Enum comments.
+-OK- Function comments.
+-OK- Var comments.
+
+-OK- Class attributes, comment before and after declaration.
+-OK- Class methods, comment of parameters in function
+  comment.
+-OK- Class methods, comment of parameters
+  after parameter declaration.
+  
+-OK- Struct attributes, comment before and after declaration.
+-OK- Struct methods, comment of parameters in function
+  comment.
+-OK- Struct methods, comment of parameters 
+  after parameter declaration.
+
+-OK- Enum items JD and Qt style, comment before items
+-OK- Enum items JD and Qt style, comment after items
+
+-OK- Class comment, with all supported tags.
+-OK- Class comment, with all doxygen tags, including
+  ignored ones.
+  
+The list of all tests, in form of shell commands to make it simple
+to test project by copying the text below into terminal program.
+make doxygen_parsing.cpptest -s
+make doxygen_translate.cpptest -s
+make doxygen_translate_all_tags.cpptest -s
+make doxygen_basic_translate.cpptest -s
+make doxygen_basic_notranslate.cpptest -s
+make doxygen_translate_links.cpptest -s
+make doxygen_tricky_constructs.cpptest -s
+
+  
+Refactoring
+===========
+
+All the code in directory _Doxygen_ should be refactored:
+-OK- all methods should be class members
+-OK- most static methods should be normal members
+-OK- replace C arrays of strings and sequential searches with STL data
+  structures and algorithms.
+-OK- use singletons instead of class instantiaion for each comment found.
+
+
+Documentation
+=============
+
+SWIG documentation will contain:
+-OK- command line options
+-OK- list of implemented features (types and placements of comments)
+-OK- list of unimplemented features (types and placements of comments)
+-OK- list of tags and their translations (all Doxygen tags).
+-OK- some amount of debugging and development information
+