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

Examples/Makefile.in

@@ -630,6 +630,7 @@ java_run:
 java_version:
 	$(JAVA) -version
 	$(JAVAC) -version || echo "Unknown javac version"
+	echo "JAVA_HOME=\"$(JAVA_HOME)\""
 
 # -----------------------------------------------------------------
 # Cleaning the java examples

Examples/java/check.list

@@ -2,6 +2,7 @@
 callback
 class
 constants
+doxygen
 enum
 extend
 funcptr

Examples/java/doxygen/Makefile

@@ -0,0 +1,21 @@
+TOP        = ../..
+SWIGEXE    = $(TOP)/../swig
+SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
+CXXSRCS    = example.cxx
+TARGET     = example
+INTERFACE  = example.i
+SWIGOPT    = -doxygen
+JAVASRCS   = *.java
+
+check: build
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' java_run
+
+build:
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \
+	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
+	SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' JAVASRCS='$(JAVASRCS)' JAVAFLAGS='$(JAVAFLAGS)' java_compile
+
+clean:
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' java_clean
+	rm -rf javadocs

Examples/java/doxygen/example.cxx

@@ -0,0 +1,48 @@
+/* File : example.cxx */
+
+#include "example.h"
+#define M_PI 3.14159265358979323846
+
+/* Move the shape to a new location */
+void Shape::move(double dx, double dy) {
+  x += dx;
+  y += dy;
+}
+
+int Shape::nshapes = 0;
+
+Circle::Circle(double r) : radius(r) {
+  NumCircles++;
+}
+
+double Circle::area() {
+  return M_PI*radius*radius;
+}
+
+double Circle::perimeter() {
+  return 2*M_PI*radius;
+}
+
+Square::Square(double w) : width(w) {
+  NumSquares++;
+}
+
+double Square::area() {
+  return width*width;
+}
+
+double Square::perimeter() {
+  return 4*width;
+}
+
+int NumSquares = 0;
+int NumCircles = 0;
+
+Square MakeSquare(double r) {
+  return Square(r);
+}
+
+Circle MakeCircle(double w) {
+  return Circle(w);
+}
+

Examples/java/doxygen/example.dsp

@@ -0,0 +1,162 @@
+# Microsoft Developer Studio Project File - Name="example" - Package Owner=<4>
+# Microsoft Developer Studio Generated Build File, Format Version 6.00
+# ** DO NOT EDIT **
+
+# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
+
+CFG=example - Win32 Release
+!MESSAGE This is not a valid makefile. To build this project using NMAKE,
+!MESSAGE use the Export Makefile command and run
+!MESSAGE 
+!MESSAGE NMAKE /f "example.mak".
+!MESSAGE 
+!MESSAGE You can specify a configuration when running NMAKE
+!MESSAGE by defining the macro CFG on the command line. For example:
+!MESSAGE 
+!MESSAGE NMAKE /f "example.mak" CFG="example - Win32 Release"
+!MESSAGE 
+!MESSAGE Possible choices for configuration are:
+!MESSAGE 
+!MESSAGE "example - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE "example - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE 
+
+# Begin Project
+# PROP AllowPerConfigDependencies 0
+# PROP Scc_ProjName ""
+# PROP Scc_LocalPath ""
+CPP=cl.exe
+MTL=midl.exe
+RSC=rc.exe
+
+!IF  "$(CFG)" == "example - Win32 Debug"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 1
+# PROP BASE Output_Dir "Debug"
+# PROP BASE Intermediate_Dir "Debug"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 1
+# PROP Output_Dir "Debug"
+# PROP Intermediate_Dir "Debug"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "_DEBUG"
+# ADD RSC /l 0x809 /d "_DEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /out:"example.dll" /pdbtype:sept
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on	"%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ELSEIF  "$(CFG)" == "example - Win32 Release"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 0
+# PROP BASE Output_Dir "Release"
+# PROP BASE Intermediate_Dir "Release"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 0
+# PROP Output_Dir "Release"
+# PROP Intermediate_Dir "Release"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD CPP /nologo /MT /W3 /GX /O2 /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "NDEBUG"
+# ADD RSC /l 0x809 /d "NDEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386 /out:"example.dll"
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on	"%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ENDIF 
+
+# Begin Target
+
+# Name "example - Win32 Debug"
+# Name "example - Win32 Release"
+# Begin Group "Source Files"
+
+# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
+# Begin Source File
+
+SOURCE=.\example.cxx
+# End Source File
+# Begin Source File
+
+SOURCE=.\example_wrap.cxx
+# End Source File
+# End Group
+# Begin Group "Header Files"
+
+# PROP Default_Filter "h;hpp;hxx;hm;inl"
+# Begin Source File
+
+SOURCE=.\example.h
+# End Source File
+# End Group
+# Begin Group "Resource Files"
+
+# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
+# End Group
+# Begin Source File
+
+SOURCE=.\example.i
+
+!IF  "$(CFG)" == "example - Win32 Debug"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+	echo In order to function correctly, please ensure the following environment variables are correctly set: 
+	echo JAVA_INCLUDE: %JAVA_INCLUDE% 
+	echo JAVA_BIN: %JAVA_BIN% 
+	echo on 
+	..\..\..\swig.exe -c++ -java "$(InputPath)" 
+	
+# End Custom Build
+
+!ELSEIF  "$(CFG)" == "example - Win32 Release"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+	echo In order to function correctly, please ensure the following environment variables are correctly set: 
+	echo JAVA_INCLUDE: %JAVA_INCLUDE% 
+	echo JAVA_BIN: %JAVA_BIN% 
+	echo on 
+	..\..\..\swig.exe -c++ -java "$(InputPath)" 
+	
+# End Custom Build
+
+!ENDIF 
+
+# End Source File
+# End Target
+# End Project

Examples/java/doxygen/example.h

@@ -0,0 +1,107 @@
+/*! \file example.h 
+This file provides a simple set of Shape classes. */
+
+/*! Base class for all shapes.
+ \author Bob
+ */
+class Shape {
+public:
+  /*! Default constructor for creating a Shape */
+  Shape() {
+    nshapes++;
+  }
+  /*! Destructor for destroying a Shape */
+  virtual ~Shape() {
+    nshapes--;
+  }
+  double x; /*!< x co-ordinate */
+  double y; /*!< y co-ordinate */
+  void    move(double dx, double dy); /*!< Move a shape to a new co-ordinate
+  \param dx x co-ordinate
+  \param dy y co-ordinate */
+  virtual double area() = 0; /*!< \return the area */
+  virtual double perimeter() = 0; /*!< \return the perimeter */
+  static  int nshapes; /*!< Number of shapes currently in existence */
+};
+
+/*! A class for representing a circle.
+ \author Jack
+ */
+class Circle : public Shape {
+private:
+  double radius;
+public:
+  /*! Construct a circle
+   *  \param r radius of the circle */
+  Circle(double r);
+  /*! Calculate the area of the circle
+   *  \return calculated area */
+  virtual double area();
+  /*! Calculate the perimeter of the circle
+   *  \return calculated perimeter of the circle */
+  virtual double perimeter();
+};
+
+/// A class for representing a square.
+class Square : public Shape {
+private:
+  double width;
+public:
+  /** Construct a square
+   *  \param w width of the square */
+  Square(double w);
+  /** Calculate the area of the square
+   *  \return calculated area */
+  virtual double area();
+  /** Calculate the perimeter of the square
+   *  \return calculated perimeter of the square */
+  virtual double perimeter();
+};
+
+/// A class for representing a rectangle, templated on the type for the rectangle dimensions
+template<typename T>
+class Rectangle : public Shape {
+private:
+  T height;
+  T width;
+public:
+  /** Construct a rectangle
+   *  \param h height of the rectangle
+   *  \param w width of the rectangle */
+  Rectangle(T h, T w) : height(h), width(w) {}
+  /** Calculate the area of the rectangle
+   *  \return calculated area */
+  virtual double area() { return width*height; }
+  /** Calculate the perimeter of the rectangle
+   *  \return calculated perimeter of the rectangle */
+  virtual double perimeter() { return 2*height + 2*width; }
+};
+
+
+/*! Factory function for creating a square
+ *  \param r width of the square
+ *  \return a fully constructed square */
+Square MakeSquare(double r);
+
+/*! Factory function for creating a circle
+ *  \param w radius of the circle
+ *  \return a fully constructed circle */
+Circle MakeCircle(double w);
+
+/*! Factory function for creating a rectangle
+ *  \param h height of the rectangle
+ *  \param w width of the rectangle
+ *  \return a fully constructed rectangle */
+template<typename T>
+Rectangle<T> MakeRectangle(T h, T w) {
+  return Rectangle<T>(h, w);
+}
+
+
+
+/*! Total number of circles ever created */
+extern int NumCircles;
+
+/// Total number of squares ever created
+extern int NumSquares;
+

Examples/java/doxygen/example.i

@@ -0,0 +1,17 @@
+%module example
+
+%{
+#include "example.h"
+%}
+
+%immutable NumSquares;
+%immutable NumCircles;
+
+%include "example.h"
+
+/*! - this instantiation uses type int */
+%template(RectangleInt) Rectangle<int>;
+
+/*! - this instantiation uses type int */
+%template(MakeRectangleInt) MakeRectangle<int>;
+

Examples/java/doxygen/runme.java

@@ -0,0 +1,63 @@
+// This example shows simple usage of the wrapped Shape classes.
+// The main purpose of this example is to show the doxygen comments translation to JavaDoc comments.
+// Users should look at the generated .java files and if javadoc is installed and working on your system,
+// the generated Java docs can be viewed in a browser by opening the javadocs/index.html file.
+
+import java.io.*;
+
+public class runme {
+  static {
+    try {
+        System.loadLibrary("example");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[]) throws InterruptedException, IOException
+  {
+    System.out.println("Creating some objects:");
+    Circle c = example.MakeCircle(10);
+    System.out.println("    Created circle " + c);
+    Square s = example.MakeSquare(10);
+    System.out.println("    Created square " + s);
+    RectangleInt r = example.MakeRectangleInt(10, 20);
+    System.out.println("    Created rectangle " + r);
+
+    System.out.println("\nHere are some properties of the shapes:");
+    Shape[] shapes = {c, s, r};
+    for (int i=0; i<shapes.length; i++) {
+      System.out.println("   " + shapes[i].toString());
+      System.out.println("        area      = " + shapes[i].area());
+      System.out.println("        perimeter = " + shapes[i].perimeter());
+    }
+
+    String command = "javadoc -quiet -public -d javadocs example.java Shape.java Circle.java Square.java RectangleInt.java";
+    System.out.println("\nRunning: " + command);
+    Process p = Runtime.getRuntime().exec(command);
+    int exitCode = p.waitFor();
+    System.out.println("javadoc exited with code " + exitCode);
+
+    BufferedReader stdout = new BufferedReader(new InputStreamReader(p.getInputStream()));
+    BufferedReader stderr = new BufferedReader(new InputStreamReader(p.getErrorStream()));
+
+    String line = null;
+
+    System.out.println("stdout from javadoc:\n");
+    while ((line = stdout.readLine()) != null) {
+      System.out.println(line);
+    }
+
+    System.out.println("\nstderr from javadoc:\n");
+    while ((line = stderr.readLine()) != null) {
+      System.out.println(line);
+    }
+
+    if (exitCode != 0) {
+      System.out.println("No java docs were generated!\n");
+    } else {
+      System.out.println("javadoc ran successfully, open javadocs/index.html in your browser to view the generated java docs.");
+    }
+  }
+}

Examples/python/check.list

@@ -4,6 +4,7 @@ class
 constants
 contract
 docstrings
+doxygen
 enum
 exception
 exceptproxy

Examples/python/doxygen/Makefile

@@ -0,0 +1,27 @@
+TOP        = ../..
+SWIGEXE    = $(TOP)/../swig
+SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
+CXXSRCS    = example.cxx
+TARGET     = example
+INTERFACE  = example.i
+LIBS       = -lm
+SWIGOPT    = -doxygen
+
+check: build
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' python_run
+
+build:
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \
+	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
+	SWIGOPT='$(SWIGOPT)' \
+	TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' python_cpp
+
+static:
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \
+	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
+	SWIGOPT='$(SWIGOPT)' \
+	TARGET='mypython' INTERFACE='$(INTERFACE)' python_cpp_static
+
+clean:
+	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' TARGET='$(TARGET)' python_clean
+	rm -f example.html

Examples/python/doxygen/example.cxx

@@ -0,0 +1,48 @@
+/* File : example.cxx */
+
+#include "example.h"
+#define M_PI 3.14159265358979323846
+
+/* Move the shape to a new location */
+void Shape::move(double dx, double dy) {
+  x += dx;
+  y += dy;
+}
+
+int Shape::nshapes = 0;
+
+Circle::Circle(double r) : radius(r) {
+  NumCircles++;
+}
+
+double Circle::area() {
+  return M_PI*radius*radius;
+}
+
+double Circle::perimeter() {
+  return 2*M_PI*radius;
+}
+
+Square::Square(double w) : width(w) {
+  NumSquares++;
+}
+
+double Square::area() {
+  return width*width;
+}
+
+double Square::perimeter() {
+  return 4*width;
+}
+
+int NumSquares = 0;
+int NumCircles = 0;
+
+Square MakeSquare(double r) {
+  return Square(r);
+}
+
+Circle MakeCircle(double w) {
+  return Circle(w);
+}
+

Examples/python/doxygen/example.dsp

@@ -0,0 +1,152 @@
+# Microsoft Developer Studio Project File - Name="example" - Package Owner=<4>
+# Microsoft Developer Studio Generated Build File, Format Version 6.00
+# ** DO NOT EDIT **
+
+# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
+
+CFG=example - Win32 Release
+!MESSAGE This is not a valid makefile. To build this project using NMAKE,
+!MESSAGE use the Export Makefile command and run
+!MESSAGE 
+!MESSAGE NMAKE /f "example.mak".
+!MESSAGE 
+!MESSAGE You can specify a configuration when running NMAKE
+!MESSAGE by defining the macro CFG on the command line. For example:
+!MESSAGE 
+!MESSAGE NMAKE /f "example.mak" CFG="example - Win32 Release"
+!MESSAGE 
+!MESSAGE Possible choices for configuration are:
+!MESSAGE 
+!MESSAGE "example - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE "example - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE 
+
+# Begin Project
+# PROP AllowPerConfigDependencies 0
+# PROP Scc_ProjName ""
+# PROP Scc_LocalPath ""
+CPP=cl.exe
+MTL=midl.exe
+RSC=rc.exe
+
+!IF  "$(CFG)" == "example - Win32 Debug"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 1
+# PROP BASE Output_Dir "Debug"
+# PROP BASE Intermediate_Dir "Debug"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 1
+# PROP Output_Dir "Debug"
+# PROP Intermediate_Dir "Debug"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "$(PYTHON_INCLUDE)" /D "SWIG_PYTHON_INTERPRETER_NO_DEBUG" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "_DEBUG"
+# ADD RSC /l 0x809 /d "_DEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib "$(PYTHON_LIB)" /nologo /dll /debug /machine:I386 /out:"_example.pyd" /pdbtype:sept
+
+!ELSEIF  "$(CFG)" == "example - Win32 Release"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 0
+# PROP BASE Output_Dir "Release"
+# PROP BASE Intermediate_Dir "Release"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 0
+# PROP Output_Dir "Release"
+# PROP Intermediate_Dir "Release"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD CPP /nologo /MT /W3 /GX /O2 /I "$(PYTHON_INCLUDE)" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "NDEBUG"
+# ADD RSC /l 0x809 /d "NDEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib "$(PYTHON_LIB)" /nologo /dll /machine:I386 /out:"_example.pyd"
+
+!ENDIF 
+
+# Begin Target
+
+# Name "example - Win32 Debug"
+# Name "example - Win32 Release"
+# Begin Group "Source Files"
+
+# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
+# Begin Source File
+
+SOURCE=.\example.cxx
+# End Source File
+# Begin Source File
+
+SOURCE=.\example_wrap.cxx
+# End Source File
+# End Group
+# Begin Group "Header Files"
+
+# PROP Default_Filter "h;hpp;hxx;hm;inl"
+# Begin Source File
+
+SOURCE=.\example.h
+# End Source File
+# End Group
+# Begin Group "Resource Files"
+
+# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
+# End Group
+# Begin Source File
+
+SOURCE=.\example.i
+
+!IF  "$(CFG)" == "example - Win32 Debug"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+	echo In order to function correctly, please ensure the following environment variables are correctly set: 
+	echo PYTHON_INCLUDE: %PYTHON_INCLUDE% 
+	echo PYTHON_LIB: %PYTHON_LIB% 
+	echo on 
+	..\..\..\swig.exe -c++ -python "$(InputPath)" 
+	
+# End Custom Build
+
+!ELSEIF  "$(CFG)" == "example - Win32 Release"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+	echo In order to function correctly, please ensure the following environment variables are correctly set: 
+	echo PYTHON_INCLUDE: %PYTHON_INCLUDE% 
+	echo PYTHON_LIB: %PYTHON_LIB% 
+	echo on 
+	..\..\..\swig.exe -c++ -python "$(InputPath)" 
+	
+# End Custom Build
+
+!ENDIF 
+
+# End Source File
+# End Target
+# End Project

Examples/python/doxygen/example.h

@@ -0,0 +1,107 @@
+/*! \file example.h 
+This file provides a simple set of Shape classes. */
+
+/*! Base class for all shapes.
+ \author Bob
+ */
+class Shape {
+public:
+  /*! Default constructor for creating a Shape */
+  Shape() {
+    nshapes++;
+  }
+  /*! Destructor for destroying a Shape */
+  virtual ~Shape() {
+    nshapes--;
+  }
+  double x; /*!< x co-ordinate */
+  double y; /*!< y co-ordinate */
+  void    move(double dx, double dy); /*!< Move a shape to a new co-ordinate
+  \param dx x co-ordinate
+  \param dy y co-ordinate */
+  virtual double area() = 0; /*!< \return the area */
+  virtual double perimeter() = 0; /*!< \return the perimeter */
+  static  int nshapes; /*!< Number of shapes currently in existence */
+};
+
+/*! A class for representing a circle.
+ \author Jack
+ */
+class Circle : public Shape {
+private:
+  double radius;
+public:
+  /*! Construct a circle
+   *  \param r radius of the circle */
+  Circle(double r);
+  /*! Calculate the area of the circle
+   *  \return calculated area */
+  virtual double area();
+  /*! Calculate the perimeter of the circle
+   *  \return calculated perimeter of the circle */
+  virtual double perimeter();
+};
+
+/// A class for representing a square.
+class Square : public Shape {
+private:
+  double width;
+public:
+  /** Construct a square
+   *  \param w width of the square */
+  Square(double w);
+  /** Calculate the area of the square
+   *  \return calculated area */
+  virtual double area();
+  /** Calculate the perimeter of the square
+   *  \return calculated perimeter of the square */
+  virtual double perimeter();
+};
+
+/// A class for representing a rectangle, templated on the type for the rectangle dimensions
+template<typename T>
+class Rectangle : public Shape {
+private:
+  T height;
+  T width;
+public:
+  /** Construct a rectangle
+   *  \param h height of the rectangle
+   *  \param w width of the rectangle */
+  Rectangle(T h, T w) : height(h), width(w) {}
+  /** Calculate the area of the rectangle
+   *  \return calculated area */
+  virtual double area() { return width*height; }
+  /** Calculate the perimeter of the rectangle
+   *  \return calculated perimeter of the rectangle */
+  virtual double perimeter() { return 2*height + 2*width; }
+};
+
+
+/*! Factory function for creating a square
+ *  \param r width of the square
+ *  \return a fully constructed square */
+Square MakeSquare(double r);
+
+/*! Factory function for creating a circle
+ *  \param w radius of the circle
+ *  \return a fully constructed circle */
+Circle MakeCircle(double w);
+
+/*! Factory function for creating a rectangle
+ *  \param h height of the rectangle
+ *  \param w width of the rectangle
+ *  \return a fully constructed rectangle */
+template<typename T>
+Rectangle<T> MakeRectangle(T h, T w) {
+  return Rectangle<T>(h, w);
+}
+
+
+
+/*! Total number of circles ever created */
+extern int NumCircles;
+
+/// Total number of squares ever created
+extern int NumSquares;
+

Examples/python/doxygen/example.i

@@ -0,0 +1,17 @@
+%module example
+
+%{
+#include "example.h"
+%}
+
+%immutable NumSquares;
+%immutable NumCircles;
+
+%include "example.h"
+
+/*! - this instantiation uses type int */
+%template(RectangleInt) Rectangle<int>;
+
+/*! - this instantiation uses type int */
+%template(MakeRectangleInt) MakeRectangle<int>;
+

Examples/python/doxygen/runme.py

@@ -0,0 +1,28 @@
+# This example shows simple usage of the wrapped Shape classes.
+# The main purpose of this example is to show the doxygen comments translation to PyDoc comments.
+# Users should look at the generated example.py file.
+# The generated PyDoc can be viewed in a browser by opening the example.html file.
+
+import example
+
+print "Creating some objects:"
+c = example.MakeCircle(10)
+print "    Created circle", c
+s = example.MakeSquare(10)
+print "    Created square", s
+r = example.MakeRectangleInt(10, 20)
+print "    Created rectangle", r
+
+print "\nHere are some properties of the shapes:"
+for o in [c, s, r]:
+    print "   ", o
+    print "        area      = ", o.area()
+    print "        perimeter = ", o.perimeter()
+
+print "\nRunning pydoc, this is the equivalent to executing: pydoc -w ./example.py"
+
+import pydoc
+
+pydoc.writedoc("example")
+
+print "Open example.html in your browser to view the generated python docs"

Examples/test-suite/common.mk

@@ -598,6 +598,30 @@ CPP11_TEST_BROKEN = \
 #	cpp11_variadic_templates \    # Broken for some languages (such as Java)
 #	cpp11_reference_wrapper \     # No typemaps
 
+# Doxygen support test cases: can only be used with languages supporting
+# Doxygen comment translation, currently only Python and Java.
+python_HAS_DOXYGEN := 1
+java_HAS_DOXYGEN := 1
+
+$(eval HAS_DOXYGEN := $($(LANGUAGE)_HAS_DOXYGEN))
+
+ifdef HAS_DOXYGEN
+DOXYGEN_TEST_CASES += \
+	doxygen_alias \
+	doxygen_basic_notranslate \
+	doxygen_basic_translate \
+	doxygen_ignore \
+	doxygen_misc_constructs \
+	doxygen_parsing \
+	doxygen_parsing_enums \
+	doxygen_translate \
+	doxygen_translate_all_tags \
+	doxygen_translate_links \
+
+$(DOXYGEN_TEST_CASES:=.cpptest): SWIGOPT += -doxygen
+
+CPP_TEST_CASES += $(DOXYGEN_TEST_CASES)
+endif
 
 #
 # Put all the heavy STD/STL cases here, where they can be skipped if needed
@@ -747,6 +771,10 @@ check-cpp: $(CPP_TEST_CASES:=.cpptest)
 
 check-cpp11: $(CPP11_TEST_CASES:=.cpptest)
 
+ifdef HAS_DOXYGEN
+check-doxygen: $(DOXYGEN_TEST_CASES:=.cpptest)
+endif
+
 check-failing-test = \
 	$(MAKE) -s $1.$2 >/dev/null 2>/dev/null && echo "Failing test $1 passed."
 

Examples/test-suite/doxygen_alias.i

@@ -0,0 +1,22 @@
+%module doxygen_alias
+
+#ifdef SWIGJAVA
+%feature("doxygen:alias:nullptr") "null"
+#elif defined(SWIGPYTHON)
+%feature("doxygen:alias:nullptr") "None"
+#else
+%feature("doxygen:alias:nullptr") "NULL"
+#endif
+
+%inline %{
+
+class Something {};
+
+/**
+    A function returning something.
+
+    @returns A new object which may be @nullptr.
+ */
+Something* make_something() { return 0; }
+
+%}

Examples/test-suite/doxygen_basic_notranslate.i

@@ -0,0 +1,104 @@
+%module doxygen_basic_notranslate
+
+%include "doxygen_basic_translate.h"
+%feature("doxygen:notranslate") function;
+%feature("doxygen:notranslate") function2;
+%feature("doxygen:notranslate") function3;
+%feature("doxygen:notranslate") function4;
+%feature("doxygen:notranslate") function5;
+%feature("doxygen:notranslate") function6;
+%feature("doxygen:notranslate") function7;
+
+%inline %{
+
+/**
+ * \brief
+ * Brief description.
+ *
+ * The comment text
+ * \author Some author
+ * \return Some number
+ * \sa function2
+ */
+int function()
+{
+    return 0;
+}
+
+/**
+ * A test of a very very very very very very very very very very very very very very very very
+ * very very very very very long comment string.
+ */
+void function2()
+{
+}
+
+/**
+ * A test for overloaded functions
+ * This is function \b one
+ */
+void function3(int a)
+{
+}
+
+/**
+ * A test for overloaded functions
+ * This is function \b two
+ */
+void function3(int a, int b)
+{
+}
+
+/**
+ * A test of some mixed tag usage
+ * \if CONDITION
+ * This \a code fragment shows us something \.
+ * \par Minuses:
+ * \arg it's senseless
+ * \arg it's stupid
+ * \arg it's null
+ *
+ * \warning This may not work as expected
+ *
+ * \code
+ * int main() { while(true); }
+ * \endcode
+ * \endif
+ */
+void function4()
+{
+}
+
+
+void function5(int a)
+{
+}
+/**< This is a post comment. */
+
+/**
+ * Test for default args
+ * @param a Some parameter, default is 42
+ */
+void function6(int a=42)
+{
+}
+
+class Shape
+{
+public:
+  typedef Shape* superType;
+};
+
+/**
+ * Test for a parameter with difficult type
+ * (mostly for python)
+ * @param a Very strange param
+ */
+void function7(Shape::superType *a[10])
+{
+}
+
+/**
+ * Comment at the end of file should be ignored.
+ */
+%}

Examples/test-suite/doxygen_basic_translate.h

@@ -0,0 +1,5 @@
+
+/**
+ * This file contains only doxygen comment without a declaration -
+ * it should be ignored by SWIG and must not trigger syntax error.
+ */

Examples/test-suite/doxygen_basic_translate.i

@@ -0,0 +1,111 @@
+%module doxygen_basic_translate
+
+%include "doxygen_basic_translate.h"
+
+%inline %{
+
+/**
+ * \brief
+ * Brief description.
+ * 
+ * The comment text.
+ *
+ * \author Some author
+ *
+ * \return Some number
+ *
+ * \sa function2
+ */
+int function()
+{
+    return 0;
+}
+
+/**
+ * A test of a very very very very very very very very very very very very very very very very
+ * very very very very very long comment string.
+ */
+void function2()
+{
+}
+
+/**
+ * A test for overloaded functions
+ * This is function \b one
+ */
+void function3(int a)
+{
+}
+
+/**
+ * A test for overloaded functions
+ * This is function \b two
+ */
+void function3(int a, int b)
+{
+}
+
+/**
+ * A test of some mixed tag usage
+ * \if CONDITION
+ * This \a code fragment shows us something \.
+ * \par Minuses:
+ * \arg it's senseless
+ * \arg it's stupid
+ * \arg it's null
+ *
+ * \warning This may not work as expected
+ * \code
+ * int main() { while(true); }
+ * \endcode
+ * \endif
+ */
+void function4()
+{
+}
+
+
+void function5(int a)
+{
+}
+/**< This is a post comment. */
+
+/**
+ * Test for default args
+ * @param a Some parameter, default is 42
+ */
+void function6(int a=42)
+{
+}
+
+class Shape
+{
+public:
+  typedef Shape* superType;
+};
+
+/**
+ * Test for a parameter with difficult type
+ * (mostly for python)
+ * @param a Very strange param
+ */
+void function7(Shape::superType *a[10])
+{
+}
+
+/**
+    Multiple parameters test.
+
+    @param y Vertical coordinate.
+    @param x Horizontal coordinate.
+    @return Arc tangent of @c y/x.
+ */
+double Atan2(double y, double x)
+{
+    return 0;
+}
+
+/**
+ * Comment at the end of file should be ignored.
+ */
+%}

Examples/test-suite/doxygen_ignore.i

@@ -0,0 +1,41 @@
+%module doxygen_ignore
+
+%feature("doxygen:ignore:transferfull");
+%feature("doxygen:ignore:compileroptions", range="line");
+%feature("doxygen:ignore:forcpponly", range="end");
+
+#ifdef SWIGJAVA
+%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly", contents="parse");
+%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly");
+#elif defined(SWIGPYTHON)
+%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly");
+%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse");
+#else
+%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly");
+%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly");
+#endif
+
+%inline %{
+
+/**
+    A contrived example of ignoring too many commands in one comment.
+
+    @forcpponly
+    This is C++-specific.
+    @endforcpponly
+
+    @beginJavaOnly
+    This is specific to @e Java.
+    @endJavaOnly
+
+    @beginPythonOnly
+    This is specific to @b Python.
+    @endPythonOnly
+
+    @transferfull Command ignored, but anything here is still included.
+
+    @compileroptions This function must be compiled with /EHa when using MSVC.
+ */
+int * func() { }
+
+%}

Examples/test-suite/doxygen_misc_constructs.h

@@ -0,0 +1,94 @@
+/*
+ * This file contains comments which demonstrate details about Doxygen processing,
+ * so they can be emulated in SWIG doxy comment translation
+ */
+
+
+
+/**This comment without space after '*' is valid in Doxygen.
+ *
+ */
+void isNoSpaceValidA()
+{}
+
+/**.This comment without space after '*' is valid in Doxygen.
+ *
+ */
+void isNoSpaceValidB()
+{}
+
+
+/***This is not Doxygen comment.
+ *
+ */
+void isNoSpaceValidC()
+{}
+
+
+/**
+ * Backslash following\c word is a valid doxygen command. Output contains
+ * 'followingword' with 'word' in code font.
+ */
+void backslashA()
+{}
+
+// Output of escaped symbols below in doxygen generated HTML:
+// Rendered: Escaped symbols: $ @ \ & < > # % " \. :: @text ::text
+// HTML source: Escaped symbols: $ @ \ &amp; &lt; &gt; # % " \. :: @text ::text
+
+
+/**
+ * Doxy command without trailing \cspace space is ignored - nothing appears
+ * on output. Standalone \ and '\' get to output.
+ * Standalone @ and '@' get to output.
+ * Commands "in quoted \b strings are treated as plain text".
+ * Commands not recognized by Doxygen \blah @blah are ignored.
+ * Backslashes in DOS paths d:\xyz\qwe\myfile and words
+ * following them do not appear on output, we must quote them with
+ * double quotes: "d:\xyz\qwe\myfile", "@something". Single quotes do not help:
+ * 'd:\xyz\qwe\myfile'. Escaping works: d:\\xyz\\qwe\\myfile. Unix
+ * paths of course have no such problems: /xyz/qwe/myfile
+ * Commands for escaped symbols:
+ * \$ \@ \\ \& \~ \< \> \# \% \" \. \:: \@text \::text
+ */
+void backslashB()
+{}
+
+/**
+ * Backslash e at end of \e line froze SWIG \e
+ * with old comment parser. 
+ *
+ * @see MyClass::fun(char,
+ *  float)
+ */
+void backslashC()
+{}
+
+/**
+ * The next line contains expression:
+ * <pre>
+ * ['retVal < 10', 'g_counter == 23 && g_mode & 3']
+ *</pre>
+ *
+ * Both words should be emphasized \b isystem.connect.
+ * But not the last period. For \b example, comma should not be emphasized.
+ * Similar \b for: double colon.
+ *
+ * Spaces at the start of line should be taken into account:
+ * @param id used as prefix in log
+ *     statements. The default value is empty string, which is OK if
+ *     there is only one app. instance. Example:
+ *     <pre>
+ *         ctrl.setBP("func1");
+ *     </pre>
+ *     If we set the id to \c main_, we get:
+ *     <pre>
+ *         main_ctrl.setBP("func1");
+ *     </pre>
+ *
+ * @param fileName name of the log file
+ */
+void cycle(int id, char *fileName)
+{}
+
+

Examples/test-suite/doxygen_misc_constructs.i

@@ -0,0 +1,124 @@
+// This file contains tests for situations, which do not normally
+// appear in the code, but must nevertheless be handled correctly.
+
+%module doxygen_misc_constructs
+
+%warnfilter(SWIGWARN_DOXYGEN_UNKNOWN_COMMAND) backslashB;
+
+%inline %{
+
+    // Tag '@endink' must be recognized even if it is not
+    // followed by whitespace.
+
+    /** Tag endlink must be recognized also when followed by nonspace charater.
+     *
+     * @link Connection::getId() @endlink<br> */
+     
+    char g_counter;
+
+
+    /** 
+      Tag endlink must be recognized also when it is the last token
+      in the commment.
+
+      @link Connection::getId() @endlink<br>
+      @link debugIdeTraceProfilerCoverageSample.py Python example. @endlink
+     */
+    int g_zipCode;
+
+
+    // Paramter 'isReportSize' must appear in comment of the overload, which
+    // has it. Empty line before link must be preserved.
+    /**
+     * Returns address of file line.
+     *
+     * @param fileName name of the file, where the source line is located
+     * @param line line number
+     * @param isGetSize if set, for every object location both address and size are returned
+     *
+     * @link Connection::getId() @endlink <br>
+     */
+    void getAddress(int &fileName, 
+                    int line,     
+                    bool isGetSize = false) {}
+
+    // The first comment must be ignored.
+    /** 
+     * \defgroup icFacade isystem.connect Facade
+     *
+     * This page shows the core classes, which can be used to control
+     * all aspects of winIDEA, for example: debugging, analyzers, IO module, ...
+     */
+
+    /** 
+     * This class contains information for connection to winIDEA. Its methods 
+     * return reference to self, so we can use it like this:
+     * <pre>
+     * CConnectionConfig config = new CConnectionConfig();
+     * config.discoveryPort(5534).dllPath("C:\\myWinIDEA\\connect.dll").id("main");
+     * </pre>
+     *
+     * All parameters are optional. Set only what is required, default values are
+     * used for unspecified parameters.
+     * <p>
+     *
+     * @link advancedWinIDEALaunching.py Python example.@endlink <br>
+     */
+    class CConnectionConfig
+    {
+    };
+
+    // Text after '\c' must be kept unchanged in Python.
+    /**
+     * Determines how long the \c isystem.connect should wait for running 
+     * instances to respond. Only one of \c lfWaitXXX flags from IConnect::ELaunchFlags
+     * may be specified.
+     */
+    int waitTime(long waitTime) {return 33;}
+
+
+    // Line with tag \ingroup must not appear in translated comment:
+    /** \ingroup icFacade
+     *
+     * This function returns connection id.
+     */
+    int getConnection() {return 3;}
+
+    // the follwing must produce no comment in wrapper
+    /*******************************************************************/
+    char getFirstLetter() {return 'a';}
+
+    
+    /**
+     * Class description.
+     */
+    class ClassWithNestedEnum {
+    public:
+        /**
+         * Enum description.
+         */
+        typedef enum {ONE,  ///< desc of one
+                      TWO,  ///< desc of two
+                      THREE ///< desc of three
+        } ENested;
+
+    };
+
+    /**
+        An example of a list in a documentation comment.
+
+            - The first item of the list.
+            - The second list item, on
+              several indented lines,
+              showing that the indentation
+              is preserved.
+            - And the final list item after it.
+
+        And this is not a list item any more.
+     */
+    void showList() { }
+
+    #include "doxygen_misc_constructs.h"
+    
+%}
+    %include "doxygen_misc_constructs.h"

Examples/test-suite/doxygen_parsing.i

@@ -0,0 +1,129 @@
+%module doxygen_parsing
+
+%inline %{
+
+/**
+ * The class comment
+ */
+class SomeClass
+{
+};
+
+/**
+ * The function comment
+ */
+void someFunction()
+{
+}
+
+/**
+ * The enum comment
+ */
+enum SomeEnum
+{
+	SOME_ENUM_ITEM
+};
+
+/**
+ * The struct comment
+ */
+struct SomeStruct
+{
+};
+
+/**
+ * The var comment
+ */
+int someVar=42;
+
+class SomeAnotherClass
+{
+public:
+	/// First overloaded constructor.
+	SomeAnotherClass(int) { }
+
+	/// Second overloaded constructor.
+	SomeAnotherClass(const char*) { }
+
+
+	/**
+	 * The class attribute comment
+	 */
+	int classAttr;
+
+	int classAttr2; ///< The class attribute post-comment
+
+	int classAttr3; ///< The class attribute post-comment
+									//!< with details
+
+	/**
+	 * The class method comment.
+         *
+         * \link SomeAnotherClass#classMethodExtended(int, int) a link text \endlink
+	 */
+	void classMethod()
+	{
+	}
+
+	/**
+	 * The class method with parameter
+	 */
+	void classMethodExtended(
+			int a, ///< Parameter a
+			int b  ///< Parameter b
+			)
+	{
+	}
+
+	/**
+	 * The class method with parameter
+	 *
+	 * @param a Parameter a
+	 * @param b Parameter b
+	 */
+	void classMethodExtended2(int a, int b)
+	{
+	}
+};
+
+struct SomeAnotherStruct
+{
+	/**
+	 * The struct attribute comment
+	 */
+	int structAttr;
+
+	int structAttr2; ///< The struct attribute post-comment
+
+	int structAttr3; ///< The struct attribute post-comment
+									 //!< with details
+
+	/**
+	 * The struct method comment
+	 */
+	void structMethod()
+	{
+	}
+
+	/**
+	 * The struct method with parameter
+	 */
+	void structMethodExtended(
+			int a, ///< Parameter a
+			int b  ///< Parameter b
+			)
+	{
+	}
+
+	/**
+	 * The struct method with parameter
+	 *
+	 * @param a Parameter a
+	 * @param b Parameter b
+	 */
+	void structMethodExtended2(int a, int b)
+	{
+	}
+};
+
+%}

Examples/test-suite/doxygen_parsing_enums.i

@@ -0,0 +1,35 @@
+%module doxygen_parsing_enums
+
+%inline %{
+
+
+	/**
+	 * Testing comments before enum items
+	 */
+	enum SomeAnotherEnum
+	{
+		/**
+		 * The comment for the first item
+		 */
+		SOME_ITEM_1,
+		/**
+		 * The comment for the second item
+		 */
+		SOME_ITEM_2,
+		/**
+		 * The comment for the third item
+		 */
+		SOME_ITEM_3
+	};
+
+	/**
+	 * Testing comments after enum items
+	 */
+	enum SomeAnotherEnum2
+	{
+		SOME_ITEM_10, ///< Post comment for the first item
+		SOME_ITEM_20, ///< Post comment for the second item
+		SOME_ITEM_30  ///< Post comment for the third item
+	};
+
+%}

Examples/test-suite/doxygen_parsing_enums_proper.i

@@ -0,0 +1,7 @@
+%module "doxygen_parsing_enums_proper"
+
+// Test enum commenting using the proper enums in the target language
+%include "enums.swg"
+
+%include "doxygen_parsing_enums.i"
+

Examples/test-suite/doxygen_parsing_enums_simple.i

@@ -0,0 +1,6 @@
+%module "doxygen_parsing_enums_simple"
+
+// Test enum commenting using simple constants (SWIG-1.3.21 and earlier default enum wrapping for C# and Java)
+%include "enumsimple.swg"
+
+%include "doxygen_parsing_enums.i"

Examples/test-suite/doxygen_parsing_enums_typesafe.i

@@ -0,0 +1,8 @@
+%module "doxygen_parsing_enums_typesafe"
+
+// Test enum commenting using the typesafe enum pattern in the target language
+%include "enumtypesafe.swg"
+
+#define SWIG_TEST_NOCSCONST // For C# typesafe enums
+
+%include "doxygen_parsing_enums.i"

Examples/test-suite/doxygen_parsing_enums_typeunsafe.i

@@ -0,0 +1,6 @@
+%module "doxygen_parsing_enums_typeunsafe"
+
+// Test enum commenting using a type unsafe enum pattern (constant integers in a class for the enum type)
+%include "enumtypeunsafe.swg"
+
+%include "doxygen_parsing_enums.i"

Examples/test-suite/doxygen_translate.i

@@ -0,0 +1,262 @@
+%module doxygen_translate
+
+%inline %{
+
+/**
+ * \a Hello
+ * 
+ * \arg some list item
+ * 
+ * \authors lots of them
+ * 
+ * \author Zubr
+ * 
+ * \b boldword
+ * 
+ * \c codeword
+ * 
+ * \cite citationword
+ * 
+ * \code some test code \endcode
+ * 
+ * \cond SOMECONDITION
+ * Some conditional comment
+ * \endcond
+ * 
+ * \copyright some copyright
+ * 
+ * \deprecated Now use another function
+ * 
+ * \e italicword
+ * 
+ * \example someFile.txt
+ * Some details on using the example
+ * 
+ * \exception SuperError
+ * 
+ * \if ANOTHERCONDITION
+ *   First part of comment
+ *   \if SECONDCONDITION
+ *     Nested condition text
+ *   \elseif THIRDCONDITION
+ *     The third condition text
+ *   \else
+ *     The last text block
+ *   \endif
+ * \else
+ *   Second part of comment
+ *   \if CONDITION
+ *     Second part extended
+ *   \endif
+ * \endif
+ * 
+ * \ifnot SOMECONDITION
+ *   This is printed if not
+ * \endif
+ * 
+ * \image html testImage.bmp "Hello, world!" width=10cm
+ * 
+ * <ul>
+ * 
+ * \li Some unordered list
+ * \li With lots of items
+ * \li lots of lots of items
+ * 
+ * </ul>
+ * 
+ * \link someMember Some description follows \endlink
+ * 
+ * \n \n \n
+ * 
+ * \note Here
+ * is the note!
+ *
+ * \overload
+ * 
+ * \p someword
+ * 
+ * \package superPackage
+ * 
+ * \par The paragraph title
+ * The paragraph text.
+ * Maybe even multiline
+ * 
+ * \param a the first param
+ * 
+ * \remark Some remark text
+ * 
+ * \remarks Another remarks section
+ * 
+ * \result Whatever
+ * 
+ * \return it
+ * 
+ * \returns may return
+ * 
+ * \sa someOtherMethod
+ * 
+ * \see function
+ * 
+ * \since version 0.0.0.1
+ * 
+ * \throw superException
+ * 
+ * \throws RuntimeError
+ * 
+ * \todo Some very important task
+ * 
+ * \tparam b B is mentioned again...
+ * 
+ * \verbatim
+ * very long
+ * text with tags <sometag>
+ * \endverbatim
+ * 
+ * \version 0.0.0.2
+ * 
+ * \warning This is senseless!
+ * 
+ * Here goes test of symbols:
+ * \$ \@ \\ \& \~ \< \> \# \% \" \. \::
+ * 
+ * And here goes simple text
+ */
+int function(int a, float b)
+{
+    return 0;
+}
+
+/**
+ * Test for html tags. See Doxygen doc for list of tags recognized by Doxygen.
+ *
+ * <a href="http://acme.com/index.html">This is link</a>
+ * <b>bold</b>
+ * <BLOCKQUOTE cite="http://www.worldwildlife.org/who/index.html">
+ * Quotation block.
+ * </BLOCKQUOTE>
+ * <br>
+ * <center>center</center>
+ * <code>this is code</code>
+ *
+ * <DL>
+ * <DT>Starts an item title.</DT>
+ * <DD>Starts an item description.</dd>
+ * </dl>
+ *
+ * <DFN>Starts a piece of text displayed in a typewriter font.
+ * </DFN>
+ * <DIV>Starts a section with a specific style (HTML only)
+ * </DIV>
+ * <EM>Starts a piece of text displayed in an italic font.</EM>
+ *
+ * <FORM>'Form' does not generate any output.
+ * </FORM>
+ * <HR>
+ * <H1>Heading 1
+ * </H1>
+ * <H2>Heading 2
+ * </H2>
+ * <H3>Heading 3
+ * </H3>
+ * <I>Starts a piece of text displayed in an italic font.</I>
+ * <INPUT>Input tag.
+ * <IMG src="slika.png"> 
+ * <META>Meta tag.
+ * <MULTICOL>Multicol is ignored by doxygen.
+ * </MULTICOL>
+ *
+ * <OL>
+ * <LI>List item 1.</LI>
+ * <LI>List item 2.</LI>
+ * </OL>
+ *
+ * <P>Starts a new paragraph.
+ * </P>
+ * <PRE>Starts a preformatted fragment.
+ * </PRE>
+ * <SMALL>Starts a section of text displayed in a smaller font.
+ * </SMALL>
+ * <SPAN>Starts an inline text fragment with a specific style.</SPAN>
+ * <STRONG>Starts a section of bold text.</STRONG>
+ * <SUB>Starts a piece of text displayed in subscript.</SUB>
+ * <SUP>Starts a piece of text displayed in superscript.</SUP>
+ *
+ * <table border = '1'>
+ * <caption>Animals</caption>
+ * <tr><th> Column 1 </th><th> Column 2 </th></tr>
+ * <tr><td> cow      </td><td> dog      </td></tr>
+ * <tr><td> cat      </td><td> mouse    </td></tr>
+ * <tr><td> horse    </td><td> parrot   </td></tr>
+ * </table>
+ *
+ * <TT>Starts a piece of text displayed in a typewriter font.
+ * </TT>
+ * <KBD>Starts a piece of text displayed in a typewriter font.
+ * </KBD>
+ *
+ * <UL>
+ * <LI>List item 1.</LI>
+ * <LI>List item 2.</LI>
+ * <LI>List item 3.</LI>
+ * </UL>
+ *
+ * <VAR>Starts a piece of text displayed in an italic font.</VAR>
+ *
+ * \htmlonly
+ * <u>underlined \b bold text - doxy commands are ignored inside 'htmlonly' section </u>
+ * \endhtmlonly
+ */
+void htmlFunction(int a, float b)
+{
+}
+
+/** 
+ * The meaning of flags:
+ *
+ * @param byFlags bits marking required items:
+ *   <table>
+ *   <tr><th> Size in bits</th><th> Items Required </th></tr>
+ *   <tr><td> 1 - 8       </td><td>      1         </td></tr>
+ *   <tr><td> 9 - 16      </td><td>      2         </td></tr>
+ *   <tr><td> 17 - 32     </td><td>      4         </td></tr>
+ *   </table>
+ *   Almost all combinations of above flags are supported by
+ *   \c htmlTable... functions.
+ */
+void htmlTableFunction(int byFlags)
+{
+}
+
+
+/**
+ * All entities are treated as commands &copy; &trade; &reg;
+ * should work also&lt;in text
+ * &gt;
+ * &amp;
+ * &apos;
+ * &quot;
+ * &lsquo;
+ * &rsquo;
+ * &ldquo;
+ * &rdquo;
+ * &ndash;
+ * &mdash;
+ * &nbsp;
+ * &times;
+ * &minus;
+ * &sdot;
+ * &sim;
+ * &le;
+ * &ge;
+ * &larr;
+ * &rarr;
+ * Not an &text; html entity - ignored by Doxygen.
+ * Not an &text html entity - ampersand is replaced with entity.
+ */
+void htmlEntitiesFunction(int a, float b)
+{
+}
+
+
+ 
+%}

Examples/test-suite/doxygen_translate_all_tags.i

@@ -0,0 +1,399 @@
+%module doxygen_translate_all_tags
+
+%inline %{
+
+/**
+ * \a Hello
+ * 
+ * \addindex SomeLatexIndex
+ *
+ * \addtogroup someGroup "Some title"
+ *
+ * \anchor theAnchor
+ *
+ * \arg some list item
+ * 
+ * \attention This is attention!
+ * You were warned!
+ *
+ * \authors lots of them
+ * \author Zubr
+ * 
+ * \b boldword
+ * 
+ * \brief Some brief description,
+ * extended to many lines.
+ *
+ * \bug Not everything works right now...
+ * \c codeword
+ * 
+ * \callgraph
+ * \callergraph
+ * \category someCategory headerFile.h headerName
+ *
+ * \cite citationword
+ * \class someClass headerFile.h headerName
+ * \code some test code \endcode
+ */
+void func01(int a)
+{
+}
+
+ 
+/** 
+ * \cond SOMECONDITION
+ * Some conditional comment
+ * \endcond
+ * 
+ * \copybrief someClass::someMethod
+ *
+ * \copydetails someClass::someMethod2
+ *
+ * \copydoc  someClass::someMethod3
+ *
+ * \copyright some copyright
+ * 
+ * \date 1970 - 2012
+ *
+ * \def someDefine
+ *
+ * \defgroup someGroup Some titles
+ *
+ * \deprecated Now use another function
+ * 
+ * \details This is very large
+ * and detailed description of some thing
+ */
+void func02(int a)
+{
+}
+
+ 
+/**
+ * Comment for \b func03().
+ *
+ * \dir /somePath/someFolder
+ *
+ * \dontinclude someFile.h
+ *
+ * \dot
+ * digraph example {
+ * node [shape=record, fontname=Helvetica, fontsize=10];
+ * b [ label="class B" URL="\ref B"];
+ * c [ label="class C" URL="\ref C"];
+ * b -> c [ arrowhead="open", style="dashed" ];
+ * }
+ * \enddot
+ *
+ * \dotfile dotFile.dot "The caption"
+ *
+ * \e italicword
+ * 
+ * \em emphazedWord
+ *
+ * \enum someEnum
+ *
+ * \example someFile.txt
+ * Some details on using the example
+ */
+void func03(int a)
+{
+}
+
+ 
+/**
+ * 
+ * \exception SuperError
+ * 
+ * \extends someOtherFunction
+ *
+ * \f$ \sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \f$
+ *
+ * \f[
+ *     \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
+ * \f]
+ *
+ * \f{
+ *     \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
+ * \f}
+ *
+ * \file file.h
+ *
+ * \fn someFn
+ *
+ * \headerfile someHeader.h "Header name"
+ *
+ * \hideinitializer
+ *
+ * \htmlinclude htmlFile.htm
+ *
+ * \htmlonly
+ * This will only appear in hmtl
+ * \endhtmlonly
+ */
+void func04(int a)
+{
+}
+
+ 
+/**
+ * \if ANOTHERCONDITION
+ *   First part of comment
+ *   \if SECONDCONDITION
+ *     Nested condition text
+ *   \elseif THIRDCONDITION
+ *     The third condition text
+ *   \else
+ *     The last text block
+ *   \endif
+ * \else
+ *   Second part of comment
+ *   \if CONDITION
+ *     Second part extended
+ *   \endif
+ * \endif
+ * 
+ * \ifnot SOMECONDITION
+ *   This is printed if not
+ * \endif
+ * 
+ * \image html testImage.bmp "Hello, world!" asd=10qwe
+ * 
+ * \implements someFunction
+ *
+ * \include header.h
+ *
+ * \includelineno header2.h
+ *
+ * \ingroup someGroup anotherGroup
+ *
+ * \internal
+ *
+ * \invariant Some text
+ * describing invariant.
+ */
+void func05(int a)
+{
+}
+
+ 
+/**
+ * Comment for \b func06().
+ *
+ * \interface someInterface someHeader.h "Header name"
+ *
+ * \latexonly
+ * This will only appear in LATeX
+ * \endlatexonly
+ *
+ * <ul>
+ * 
+ * \li Some unordered list
+ * \li With lots of items
+ * \li lots of lots of items
+ * 
+ * </ul>
+ * 
+ * \line example
+ *
+ * \link someMember Some description follows \endlink
+ * 
+ * \mainpage Some title
+ *
+ * \manonly
+ * This will only appear in man
+ * \endmanonly
+ *
+ * \memberof someThing
+ *
+ * \msc
+ * Sender,Receiver;
+ * Sender->Receiver [label="Command()", URL="\ref Receiver::Command()"];
+ * Sender<-Receiver [label="Ack()", URL="\ref Ack()", ID="1"];
+ * \endmsc
+ *
+ * \mscfile mscFile.msc "The caption"
+ *
+ * \n \n \n
+ */
+void func06(int a)
+{
+}
+
+ 
+/**
+ * Comment for \b func07().
+ *
+ * \name someHeader.h
+ *
+ * \namespace someNamespace
+ *
+ * \nosubgrouping
+ *
+ * \note Here
+ * is the note!
+ *
+ * \overload
+ * 
+ * \p someword
+ * 
+ * \package superPackage
+ * 
+ * \page somePage The title
+ *
+ * \par The paragraph title
+ * The paragraph text.
+ * Maybe even multiline
+ * 
+ * \paragraph someParagraph Paragraph title
+ *
+ * \param a the first param
+ * 
+ * \post Some description
+ *
+ * \pre Some description
+ *
+ * \private
+ *
+ * \privatesection
+ *
+ * \property someVar
+ */
+void func07(int a)
+{
+}
+
+ 
+/**
+ * \protected
+ *
+ * \protectedsection
+ *
+ * \anchor someAnchor
+ * Text after anchor.
+ * \protocol someProtocol header.h "Header name"
+ *
+ * \public
+ *
+ * \publicsection
+ *
+ * \ref someAnchor "Anchor description"
+ *
+ * \ref someAnchor not quoted text is not part of ref tag
+ *
+ * \ref someAnchor
+ *
+ * \related toSomething
+ *
+ * \relates toSomethingElse
+ *
+ * \relatedalso someName
+ *
+ * \relatesalso someName
+ *
+ * \remark Some remark text
+ * 
+ * \remarks Another remarks section
+ * 
+ * \result Whatever
+ * 
+ * \return it
+ * 
+ * \returns may return
+ * 
+ * \retval someValue Some description
+ */
+void func08(int a)
+{
+}
+
+ 
+/**
+ * \rtfonly
+ * This will only appear in RTF
+ * \endrtfonly
+ *
+ * \sa someOtherMethod
+ * 
+ * \section someSection Some title
+ *
+ * \see function
+ * 
+ * \short Same as
+ * brief description
+ *
+ * \showinitializer
+ *
+ * \since version 0.0.0.1
+ * 
+ * \skip somePattern
+ *
+ * \skipline someLine
+ *
+ * \snippet example.h Some snippet
+ *
+ * \struct someStruct
+ *
+ * \subpage someSubpage "Some description"
+ *
+ * \subsection someSubsection Some title
+ *
+ * \subsubsection someSubsection Some title
+ *
+ * \tableofcontents
+ *
+ * \test Some
+ * description of the
+ * test case
+ *
+ * \throw superException
+ * 
+ * \throws RuntimeError
+ */
+void func09(int a)
+{
+}
+
+ 
+/**
+ * \todo Some very important task
+ * 
+ * \tparam b B is mentioned again...
+ * 
+ * \typedef someTypedef
+ *
+ * \union someUnion
+ *
+ * \until somePattern
+ *
+ * \var someVar
+ *
+ * \verbatim
+ * very long
+ * text with tags <sometag>
+ * \endverbatim
+ * 
+ * \verbinclude someFile.h
+ *
+ * \version 0.0.0.2
+ * 
+ * \warning This is senseless!
+ * 
+ * \weakgroup someGroup Some title
+ *
+ * \xmlonly
+ * This will only appear in XML
+ * \endxmlonly
+ *
+ * \xrefitem todo "Todo" "Todo List"
+ *
+ * Here goes test of symbols:
+ * \$ \@ \\ \& \~ \< \> \# \% \" \. \::
+ * 
+ * And here goes simple text
+ */
+void func10(int a, float b)
+{
+}
+
+%}

Examples/test-suite/doxygen_translate_links.i

@@ -0,0 +1,67 @@
+
+
+%module doxygen_translate_links
+%include "std_string.i"
+
+%inline %{
+
+class Shape
+{
+public:
+  typedef Shape* superType;
+};
+
+/**
+ * Testing typenames converting in \@ link
+ *
+ * \link superFunc(int,std::string)
+ * Test for std_string member
+ * \endlink
+ *
+ * \link superFunc(int,long,void*)
+ * Test for simple types
+ * \endlink
+ *
+ * \link superFunc(Shape::superType*)
+ * Test for custom types
+ * \endlink
+ * 
+ * \link superFunc(int**[13])
+ * Test for complex types
+ * \endlink
+ * 
+ * same works for 'See also:' links:
+ *
+ * \sa superFunc(int,std::string)
+ * \sa superFunc(int,long,void*)
+ * \sa superFunc(Shape::superType*)
+ * \sa superFunc(int**[13])
+ * 
+ * some failing params:
+ *
+ * \sa superFunc()
+ * \sa superFunc()
+ * \sa superFunc()
+ *
+ */
+void function()
+{
+}
+
+void superFunc(int, std::string)
+{
+}
+
+void superFunc(int, long, void *)
+{
+}
+
+void superFunc(Shape::superType *)
+{
+}
+
+void superFunc(int **arr[13])
+{
+}
+
+%}

Examples/test-suite/errors/Makefile.in

@@ -27,12 +27,24 @@ SWIGINVOKE   = $(SWIG_LIB_SET) $(SWIGTOOL) $(SWIGEXE)
 ALL_ERROR_TEST_CASES := $(patsubst %.i,%, $(notdir $(wildcard $(srcdir)/*.i)))
 CPP_ERROR_TEST_CASES := $(filter cpp_%, $(ALL_ERROR_TEST_CASES))
 C_ERROR_TEST_CASES := $(filter-out $(CPP_ERROR_TEST_CASES), $(ALL_ERROR_TEST_CASES))
+DOXYGEN_ERROR_TEST_CASES := $(filter doxygen_%, $(C_ERROR_TEST_CASES))
+C_ERROR_TEST_CASES := $(filter-out $(DOXYGEN_ERROR_TEST_CASES), $(C_ERROR_TEST_CASES))
+
+# Always use C++ for Doxygen tests, there doesn't seem to be any need to
+# distinguish between C and C++ Doxygen tests.
+DOXYGEN_ERROR_TEST_CASES := $(DOXYGEN_ERROR_TEST_CASES:=.cpptest)
 
 ERROR_TEST_CASES := $(CPP_ERROR_TEST_CASES:=.cpptest) \
-		    $(C_ERROR_TEST_CASES:=.ctest)
+		    $(C_ERROR_TEST_CASES:=.ctest) \
+		    $(DOXYGEN_ERROR_TEST_CASES)
 
 include $(srcdir)/../common.mk
 
+# This is tricky: we need to let common.mk define SWIGOPT before appending to
+# it, if we do it before including it, its defining of SWIGOPT would override
+# whatever we do here.
+$(DOXYGEN_ERROR_TEST_CASES): SWIGOPT += -doxygen
+
 # Portable dos2unix / todos for stripping CR
 TODOS        = tr -d '\r'
 #TODOS        = sed -e 's/\r$$//' # On Mac OS X behaves as if written 's/r$$//'

Examples/test-suite/errors/doxygen_unknown_command.i

@@ -0,0 +1,6 @@
+%module xxx
+
+/**
+    There is an \unknown Doxygen comment here.
+ */
+void foo();

Examples/test-suite/errors/doxygen_unknown_command.stderr

@@ -0,0 +1 @@
+doxygen_unknown_command.i:4: Warning 560: Unknown Doxygen command: unknown.

Examples/test-suite/java/CommentParser.java

@@ -0,0 +1,168 @@
+
+import com.sun.javadoc.*;
+import java.util.HashMap;
+import java.util.Map.Entry;
+import java.util.Map;
+import java.util.Set;
+import java.util.Iterator;
+import java.io.BufferedWriter;
+import java.io.OutputStreamWriter;
+import java.io.FileOutputStream;
+import java.io.IOException;
+
+
+public class CommentParser {
+    private static Map<String, String> m_parsedComments = new HashMap<String, String>();
+
+    public static boolean start(RootDoc root) {
+
+        /*
+         * This method is called by 'javadoc' and gets the whole parsed java
+         * file, we get comments and store them
+         */
+
+        for (ClassDoc classDoc : root.classes()) {
+
+            if (classDoc.getRawCommentText().length() > 0)
+                m_parsedComments.put(classDoc.qualifiedName(), classDoc.getRawCommentText());
+
+            for (FieldDoc f : classDoc.enumConstants()) {
+                if (f.getRawCommentText().length() > 0)
+                    m_parsedComments.put(f.qualifiedName(), f.getRawCommentText());
+            }
+            for (FieldDoc f : classDoc.fields()) {
+                if (f.getRawCommentText().length() > 0)
+                    m_parsedComments.put(f.qualifiedName(), f.getRawCommentText());
+            }
+            for (MethodDoc m : classDoc.methods()) {
+                if (m.getRawCommentText().length() > 0)
+                    m_parsedComments.put(m.toString(), m.getRawCommentText());
+            }
+        }
+        return true;
+    }
+
+    
+    public int check(Map<String, String> wantedComments) {
+        int errorCount=0;
+        Iterator<Entry<String, String>> it = m_parsedComments.entrySet().iterator();
+
+        while (it.hasNext()) {
+            
+            Entry<String, String> e = (Entry<String, String>) it.next();
+            String actualStr = e.getValue();
+            String wantedStr = wantedComments.get(e.getKey());
+            // this may be weird, but I don't know any more effective solution
+            actualStr = actualStr.replace(" ", "");
+            actualStr = actualStr.replaceAll("\t", "");
+            actualStr = actualStr.replace("\n", "");
+            
+            // Removing of <br> is temporary solution, since adding of
+            // <br> tag requires changes in all tests. However, <br>
+            // tag should be added more selectively and when this is
+            // implemented, tests should be updated.
+            actualStr = actualStr.replace("<br>", "");
+            
+            if (wantedStr != null) {
+                wantedStr = wantedStr.replace(" ", "");
+                wantedStr = wantedStr.replace("\t", "");
+                wantedStr = wantedStr.replace("\n", "");
+                wantedStr = wantedStr.replace("<br>", "");
+            }
+            /* The following lines replace multiple whitespaces with a single one.
+               Although this would be more exact testing, it would also require
+               more work on test maintenance.
+            actualStr = actualStr.replace('\t', ' ');
+            actualStr = actualStr.replaceAll(" +", " ");
+            // actualStr = actualStr.replace("\n", "");
+            if (wantedStr != null) {
+                wantedStr = wantedStr.replace('\t', ' ');
+                wantedStr = wantedStr.replaceAll(" +", " ");
+                // wantedStr = wantedStr.replace("\n", "");
+                } */
+
+            if (!actualStr.equals(wantedStr)) {
+                System.out.println("\n\n////////////////////////////////////////////////////////////////////////");
+                System.out.println("Documentation comments for '" + e.getKey() + "' do not match!");
+                String expectedFileName = "expected.txt";
+                String gotFileName = "got.txt";
+                System.out.println("Output is also saved to files '" + expectedFileName +
+                                   "' and '" + gotFileName + "'");
+                // here we print original strings, for nicer output
+                System.out.println("\n\n---\nexpected:\n" + wantedComments.get(e.getKey()));
+                System.out.println("\n\n---\ngot:\n" + e.getValue());
+
+                try {
+                    // write expected string to file
+                    BufferedWriter expectedFile = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(expectedFileName)));
+                    expectedFile.write(wantedComments.get(e.getKey()));
+                    expectedFile.close();
+
+                    // write translated string to file
+                    BufferedWriter gotFile = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(gotFileName)));
+                    gotFile.write(e.getValue().replace("<br>", ""));
+                    gotFile.close();
+                } catch (IOException ex) {
+                    System.out.println("Error when writing output to file: " + ex);
+                }
+                
+                errorCount++;
+            }
+        }
+
+        if (m_parsedComments.size() != wantedComments.size()) {
+            System.out.println("Mismatch in the number of comments!\n    Expected: " +
+                               wantedComments.size() + "\n    Parsed: " +
+                               m_parsedComments.size());
+            System.out.println("Expected keys: ");
+            printKeys(wantedComments);
+            System.out.println("Parsed keys: ");
+            printKeys(m_parsedComments);
+
+            errorCount++;
+        }
+		
+        return errorCount > 0 ? 1 : 0;
+    }
+
+    
+    private void printKeys(Map<String, String> map) {
+        
+        Set<String> keys = map.keySet();
+        for (String key : keys) {
+            System.out.println("    " + key);
+        }
+    }
+    
+    
+    public static void printCommentListForJavaSource() {
+
+        Iterator< Entry<String, String> > it = m_parsedComments.entrySet().iterator();
+        
+        while (it.hasNext())  {
+            
+            Entry<String, String> e = (Entry<String, String>) it.next();
+            String commentText = e.getValue();
+            commentText = commentText.replace("\\", "\\\\");
+            commentText = commentText.replace("\"", "\\\"");
+            commentText = commentText.replace("\n", "\\n\" +\n\t\t\"");
+            System.out.format("wantedComments.put(\"%s\",\n\t\t\"%s\");\n", e.getKey(), commentText);
+        }
+    }
+
+    
+    public static void main(String argv[]) {
+		
+        if (argv.length<1) {
+            System.out.format("Usage:\n\tCommentParser <package to parse>\n");
+            System.exit(1);
+        }
+		
+        com.sun.tools.javadoc.Main.execute("The comment parser program",
+                                           "CommentParser", new String[]{"-quiet", argv[0]});
+		
+        // if we are run as standalone app, print the list of found comments as it would appear in java source
+		
+        printCommentListForJavaSource();
+    }
+}

Examples/test-suite/java/Makefile.in

@@ -6,8 +6,11 @@ LANGUAGE     = java
 JAVA         = @JAVA@
 JAVAC        = @JAVAC@
 JAVAFLAGS    = @JAVAFLAGS@
+JAVA_CLASSPATH_SEP = @JAVA_CLASSPATH_SEP@
 SCRIPTSUFFIX = _runme.java
 
+JAVA_HOME ?= @JAVA_HOME@
+
 srcdir       = @srcdir@
 top_srcdir   = ../@top_srcdir@
 top_builddir = ../@top_builddir@
@@ -50,6 +53,12 @@ CPP11_TEST_CASES = \
 	cpp11_shared_ptr_upcast \
 	cpp11_strongly_typed_enumerations_simple \
 
+DOXYGEN_TEST_CASES := \
+	doxygen_parsing_enums_simple \
+	doxygen_parsing_enums_proper \
+	doxygen_parsing_enums_typesafe \
+	doxygen_parsing_enums_typeunsafe \
+
 include $(srcdir)/../common.mk
 
 # Overridden variables here
@@ -95,14 +104,20 @@ setup = \
 	  mkdir $(JAVA_PACKAGE);							  \
 	fi
 
+# Doxygen test cases need to be compiled together with the CommentsParser class
+# which depends on com.sun.javadoc package which is located in this JAR.
+JAVA_CLASSPATH := .
+$(DOXYGEN_TEST_CASES:=.cpptest): JAVA_CLASSPATH := "$(JAVA_HOME)/lib/tools.jar$(JAVA_CLASSPATH_SEP)."
+$(DOXYGEN_TEST_CASES:=.cpptest): DOXYGEN_COMMENT_PARSER := $(srcdir)/CommentParser.java
+
 # Compiles java files then runs the testcase. A testcase is only run if
 # a file is found which has _runme.java appended after the testcase name.
 # Note Java uses LD_LIBRARY_PATH under Unix, PATH under Cygwin/Windows, SHLIB_PATH on HPUX and DYLD_LIBRARY_PATH on Mac OS X.
 run_testcase = \
 	cd $(JAVA_PACKAGE) && $(COMPILETOOL) $(JAVAC) -classpath . `find . -name "*.java"` && cd .. && \
 	if [ -f $(SCRIPTDIR)/$(SCRIPTPREFIX)$*$(SCRIPTSUFFIX) ]; then \
-	  $(COMPILETOOL) $(JAVAC) -classpath . -d . $(SCRIPTDIR)/$(SCRIPTPREFIX)$*$(SCRIPTSUFFIX) && \
-	  env LD_LIBRARY_PATH="$(JAVA_PACKAGE):$$LD_LIBRARY_PATH" PATH="$(JAVA_PACKAGE):$$PATH" SHLIB_PATH="$(JAVA_PACKAGE):$$SHLIB_PATH" DYLD_LIBRARY_PATH="$(JAVA_PACKAGE):$$DYLD_LIBRARY_PATH" $(RUNTOOL) $(JAVA) $(JAVAFLAGS) -classpath . $*_runme; \
+	  $(COMPILETOOL) $(JAVAC) -classpath $(JAVA_CLASSPATH) -d . $(DOXYGEN_COMMENT_PARSER) $(SCRIPTDIR)/$(SCRIPTPREFIX)$*$(SCRIPTSUFFIX) && \
+	  env LD_LIBRARY_PATH="$(JAVA_PACKAGE):$$LD_LIBRARY_PATH" PATH="$(JAVA_PACKAGE):$$PATH" SHLIB_PATH="$(JAVA_PACKAGE):$$SHLIB_PATH" DYLD_LIBRARY_PATH="$(JAVA_PACKAGE):$$DYLD_LIBRARY_PATH" $(RUNTOOL) $(JAVA) $(JAVAFLAGS) -classpath $(JAVA_CLASSPATH) $*_runme; \
 	fi
 
 # Clean: remove testcase directories

Examples/test-suite/java/doxygen_alias_runme.java

@@ -0,0 +1,32 @@
+
+import doxygen_alias.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_alias_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_alias");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[])
+  {
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_alias runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_alias"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    wantedComments.put("doxygen_alias.doxygen_alias.make_something()",
+      "     A function returning something.<br>\n" +
+      " <br>\n" +
+      "     @return A new object which may be null.\n" +
+      "");
+
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_basic_notranslate_runme.java

@@ -0,0 +1,101 @@
+
+import doxygen_basic_notranslate.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_basic_notranslate_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_basic_notranslate");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_basic_notranslate runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_basic_notranslate"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function3(int)",
+    		" \n" +
+    		"  A test for overloaded functions\n" +
+    		"  This is function \\b one\n" +
+    		"  \n" +
+    		"");
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function4()",
+    		" \n" +
+    		"  A test of some mixed tag usage\n" +
+    		"  \\if CONDITION\n" +
+    		"  This \\a code fragment shows us something \\.\n" +
+    		"  \\par Minuses:\n" +
+    		"  \\arg it's senseless\n" +
+    		"  \\arg it's stupid\n" +
+    		"  \\arg it's null\n" +
+    		" \n" +
+    		"  \\warning This may not work as expected\n" +
+    		" \n" +
+    		"  \\code\n" +
+    		"  int main() { while(true); }\n" +
+    		"  \\endcode\n" +
+    		"  \\endif\n" +
+    		"  \n" +
+    		"");
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function()",
+    		" \n" +
+    		"  \\brief\n" +
+    		"  Brief description.\n" +
+    		"  \n" +
+    		"  The comment text\n" +
+    		"  \\author Some author\n" +
+    		"  \\return Some number\n" +
+    		"  \\sa function2\n" +
+    		"  \n" +
+    		"");
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function5(int)",
+    		"  This is a post comment. \n" +
+    		"");
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function7(doxygen_basic_notranslate.SWIGTYPE_p_p_p_Shape)",
+    		" \n" +
+    		"  Test for a parameter with difficult type\n" +
+    		"  (mostly for python)\n" +
+    		"  @param a Very strange param\n" +
+    		"  \n" +
+    		"");
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function3(int, int)",
+    		" \n" +
+    		"  A test for overloaded functions\n" +
+    		"  This is function \\b two\n" +
+    		"  \n" +
+    		"");
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function6(int)",
+    		" \n" +
+    		"  Test for default args\n" +
+    		"  @param a Some parameter, default is 42\n" +
+    		"  \n" +
+    		"");
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function6()",
+    		" \n" +
+    		"  Test for default args\n" +
+    		"  @param a Some parameter, default is 42\n" +
+    		"  \n" +
+    		"");
+    wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function2()",
+    		" \n" +
+    		"  A test of a very very very very very very very very very very very very very very very very\n" +
+    		"  very very very very very long comment string.\n" +
+    		"  \n" +
+    		"");
+    
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_basic_translate_runme.java

@@ -0,0 +1,99 @@
+
+import doxygen_basic_translate.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_basic_translate_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_basic_translate");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_basic_translate runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_basic_translate"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function()",
+    		" \n" +
+    		" Brief description.\n" +
+    		" \n" +
+    		" The comment text.\n" +
+    		" @author Some author\n" +
+    		" @return Some number\n" +
+    		" @see function2\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function2()",
+    		" A test of a very very very very very very very very very very very very very very very very \n" +
+    		" very very very very very long comment string. \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function4()",
+    		" A test of some mixed tag usage \n" +
+    		" If: CONDITION {\n" +
+    		" This <i>code </i>fragment shows us something . \n" +
+    		" <p alt=\"Minuses: \">\n" +
+    		" <li>it's senseless \n" +
+    		" </li><li>it's stupid \n" +
+    		" </li><li>it's null \n" +
+    		" \n" +
+    		" </li></p>Warning: This may not work as expected \n" +
+    		" \n" +
+    		" {@code \n" +
+    		"int main() { while(true); } \n" +
+    		" }\n" +
+    		" }\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function3(int)",
+    		" A test for overloaded functions \n" +
+    		" This is function <b>one </b>\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function5(int)",
+    		" This is a post comment. \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function6(int)",
+    		" Test for default args \n" +
+    		" @param a Some parameter, default is 42" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function6()",
+    		" Test for default args \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function7(doxygen_basic_translate.SWIGTYPE_p_p_p_Shape)",
+    		" Test for a parameter with difficult type \n" +
+    		" (mostly for python) \n" +
+    		" @param a Very strange param \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function3(int, int)",
+    		" A test for overloaded functions \n" +
+    		" This is function <b>two </b>\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.Atan2(double, double)",
+    		" Multiple parameters test.\n" +
+    		" \n" +
+    		" @param y Vertical coordinate.\n" +
+    		" @param x Horizontal coordinate.\n" +
+    		" @return Arc tangent of <code>y/x</code>.\n" +
+    		"");
+
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_ignore_runme.java

@@ -0,0 +1,44 @@
+
+import doxygen_ignore.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_ignore_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_ignore");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[]) 
+  {
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_ignore runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_ignore"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    wantedComments.put("doxygen_ignore.doxygen_ignore.func()",
+      "     A contrived example of ignoring too many commands in one comment.<br>\n" +
+      " <br>\n" +
+      " <br>\n" +
+      " <br>\n" +
+      " <br>\n" +
+      "     This is specific to <i>Java</i>.<br>\n" +
+      "     <br>\n" +
+      " <br>\n" +
+      " <br>\n" +
+      " <br>\n" +
+      "     Command ignored, but anything here is still included.<br>\n" +
+      " <br>\n" +
+      "\n" +
+      "\n" +
+      "\n" +
+      "");
+
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_misc_constructs_runme.java

@@ -0,0 +1,197 @@
+
+import doxygen_misc_constructs.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_misc_constructs_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_misc_constructs");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_misc_constructs runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_misc_constructs"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getConnection()",
+    		"\n" +
+    		"\n" +
+    		" This function returns connection id.\n" +
+    		"\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getAddress(doxygen_misc_constructs.SWIGTYPE_p_int, int)",
+    		" Returns address of file line.\n" +
+    		" \n" +
+    		" @param fileName name of the file, where the source line is located\n" +
+    		" @param line line number\n" +
+    		" {@link Connection::getId()  }<br>\n" +
+    		"\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getG_zipCode()",
+    		" Tag endlink must be recognized also when it is the last token\n" +
+    		" in the commment.\n" +
+    		" \n" +
+    		" {@link Connection::getId()  }<br>\n" +
+    		" {@link debugIdeTraceProfilerCoverageSample.py Python example.  }\n" +
+    		"\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.setG_zipCode(int)",
+    		" Tag endlink must be recognized also when it is the last token\n" +
+    		" in the commment.\n" +
+    		"\n" +
+    		" {@link Connection::getId()  }<br>\n" +
+    		" {@link debugIdeTraceProfilerCoverageSample.py Python example.  }\n" +
+    		"\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getG_counter()",
+    		" Tag endlink must be recognized also when followed by nonspace charater.\n" +
+    		"\n" +
+    		" {@link Connection::getId()  }<br>\n" +
+    		"\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.waitTime(int)",
+    		" Determines how long the <code>isystem.connect</code> should wait for running\n" +
+    		" instances to respond. Only one of <code>lfWaitXXX</code> flags from IConnect::ELaunchFlags\n" +
+    		" may be specified.\n" +
+    		"\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.CConnectionConfig",
+    		" This class contains information for connection to winIDEA. Its methods\n" +
+    		" return reference to self, so we can use it like this:\n" +
+    		" <pre>\n" +
+    		" CConnectionConfig config = new CConnectionConfig();\n" +
+    		" config.discoveryPort(5534).dllPath(\"C:\\\\myWinIDEA\\\\connect.dll\").id(\"main\");\n" +
+    		" </pre>\n" +
+    		"\n" +
+    		" All parameters are optional. Set only what is required, default values are\n" +
+    		" used for unspecified parameters.\n" +
+    		" <p>\n" +
+    		"\n" +
+    		" {@link advancedWinIDEALaunching.py Python example.  }<br>\n" +
+    		"\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getAddress(doxygen_misc_constructs.SWIGTYPE_p_int, int, boolean)",
+    		" Returns address of file line.\n" +
+    		"\n" +
+    		" @param fileName name of the file, where the source line is located\n" +
+    		" @param line line number\n" +
+    		" @param isGetSize if set, for every object location both address and size are returned\n" +
+    		"\n" +
+    		" {@link Connection::getId()  }<br>\n" +
+    		"\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.setG_counter(char)",
+    		" Tag endlink must be recognized also when followed by nonspace charater.\n" +
+    		"\n" +
+    		" {@link Connection::getId()  }<br>\n" +
+    		"\n" +
+    		"");
+
+    wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum",
+    		" Class description.\n" +
+    		"\n");
+
+    wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested",
+    		" Enum description.\n" +
+    		"\n");
+
+    wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.ONE",
+    		" desc of one\n");
+
+    wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.TWO",
+    		" desc of two\n");
+
+    wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.THREE",
+    		" desc of three\n");
+
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.showList()",
+"         An example of a list in a documentation comment.<br>\n" +
+" <br>\n" +
+"             - The first item of the list.<br>\n" +
+"             - The second list item, on<br>\n" +
+"               several indented lines,<br>\n" +
+"               showing that the indentation<br>\n" +
+"               is preserved.<br>\n" +
+"             - And the final list item after it.<br>\n" +
+" <br>\n" +
+"        And this is not a list item any more.\n" +
+    		"");
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.isNoSpaceValidA()",
+    		" This comment without space after '*' is valid in Doxygen.\n" +
+    		"\n" +
+    		"");
+ 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.isNoSpaceValidB()",
+    		" .This comment without space after '*' is valid in Doxygen.\n" +
+    		"\n" +
+    		"");
+ 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.backslashA()",
+    		" Backslash following<code>word</code> is a valid doxygen command. Output contains\n" +
+    		" 'followingword' with 'word' in code font.\n" +
+    		"\n" +
+    		"");
+ 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.backslashB()",
+                       " Doxy command without trailing space is ignored - nothing appears\n" +
+                       " on output. Standalone \\ and '\\' get to output.\n" +
+                       " Standalone @ and '@' get to output.\n" +
+                       " Commands \"in quoted \\b strings are treated as plain text\".\n" +
+                       " Commands not recognized by Doxygen are ignored.\n" +
+                       " Backslashes in DOS paths d:and words\n" +
+                       " following them do not appear on output, we must quote them with\n" +
+                       " double quotes: \"d:\\xyz\\qwe\\myfile\", \"@something\". Single quotes do not help:\n" +
+                       " 'd:'. Escaping works: d:\\xyz\\qwe\\myfile. Unix\n" +
+                       " paths of course have no such problems: /xyz/qwe/myfile\n" +
+                       " Commands for escaped symbols:\n" +
+                       " $ @ \\ &amp; ~ &lt; &gt; # % &quot; . :: @text ::text" +
+    		"\n");
+
+   wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.backslashC()",
+    		" Backslash e at end of <i>line</i> froze SWIG\n" +
+    		" <i>with</i> old comment parser.\n" +
+                " @see MyClass#fun(char,float)\n" +
+    		"");
+
+   wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.cycle(int, java.lang.String)",
+    		" The next line contains expression:\n" +
+                " <pre>\n" +
+    		" ['retVal &lt; 10', 'g_counter == 23 &amp;&amp; g_mode &amp; 3']\n" +
+                " </pre>\n" +
+    		"\n" +
+                " Both words should be emphasized <b>isystem.connect</b>.\n" +
+                " But not the last period. For <b>example</b>, comma should not be emphasized.\n" +
+                " Similar <b>for</b>: double colon.\n" +
+    		"\n" +
+                " Spaces at the start of line should be taken into account:\n" +
+                " @param id used as prefix in log\n" +
+                "     statements. The default value is empty string, which is OK if\n" +
+                "     there is only one app. instance. Example:\n" +
+                "     <pre>\n" +
+                "         ctrl.setBP(\"func1\");\n" +
+                "     </pre>\n" +
+                "     If we set the id to <code>main_</code>, we get:\n" +
+                "     <pre>\n" +
+                "         main_ctrl.setBP(\"func1\");\n" +
+                "     </pre>\n" +
+                "\n" +
+                " @param fileName name of the log file\n");
+ 
+    
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java

@@ -0,0 +1,62 @@
+
+import doxygen_parsing_enums_proper.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_parsing_enums_proper_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_parsing_enums_proper");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_parsing_enums_proper runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_parsing_enums_proper"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2.SOME_ITEM_10",
+    		"Post comment for the first item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum.SOME_ITEM_1",
+    		" The comment for the first item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum",
+    		" Testing comments before enum items \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2.SOME_ITEM_30",
+    		"Post comment for the third item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2",
+    		" Testing comments after enum items \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum.SOME_ITEM_3",
+    		" The comment for the third item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum.SOME_ITEM_2",
+    		" The comment for the second item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2.SOME_ITEM_20",
+    		"Post comment for the second item \n" +
+    		"");
+    
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java

@@ -0,0 +1,54 @@
+
+import doxygen_parsing_enums_simple.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_parsing_enums_simple_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_parsing_enums_simple");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_parsing_enums_simple runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_parsing_enums_simple"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_30",
+    		"Post comment for the third item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_3",
+    		" The comment for the third item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_2",
+    		" The comment for the second item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_10",
+    		"Post comment for the first item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_20",
+    		"Post comment for the second item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_1",
+    		" The comment for the first item \n" +
+    		" \n" +
+    		"");
+    
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java

@@ -0,0 +1,63 @@
+
+import doxygen_parsing_enums_typesafe.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_parsing_enums_typesafe_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_parsing_enums_typesafe");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_parsing_enums_typesafe runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_parsing_enums_typesafe"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum.SOME_ITEM_1",
+    		" The comment for the first item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2",
+    		" Testing comments after enum items \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum.SOME_ITEM_2",
+    		" The comment for the second item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2.SOME_ITEM_20",
+    		"Post comment for the second item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum",
+    		" Testing comments before enum items \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2.SOME_ITEM_10",
+    		"Post comment for the first item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum.SOME_ITEM_3",
+    		" The comment for the third item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2.SOME_ITEM_30",
+    		"Post comment for the third item \n" +
+    		"");
+
+    
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java

@@ -0,0 +1,62 @@
+
+import doxygen_parsing_enums_typeunsafe.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_parsing_enums_typeunsafe_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_parsing_enums_typeunsafe");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_parsing_enums_typeunsafe runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_parsing_enums_typeunsafe"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum.SOME_ITEM_2",
+    		" The comment for the second item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum.SOME_ITEM_3",
+    		" The comment for the third item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum.SOME_ITEM_1",
+    		" The comment for the first item \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2.SOME_ITEM_20",
+    		"Post comment for the second item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum",
+    		" Testing comments before enum items \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2",
+    		" Testing comments after enum items \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2.SOME_ITEM_30",
+    		"Post comment for the third item \n" +
+    		"");
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2.SOME_ITEM_10",
+    		"Post comment for the first item \n" +
+    		"");
+    
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_parsing_runme.java

@@ -0,0 +1,132 @@
+
+import doxygen_parsing.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_parsing_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_parsing");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_parsing runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_parsing"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.getClassAttr()",
+    		" The class attribute comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr3(int)",
+    		"The class attribute post-comment with details \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.setStructAttr3(int)",
+    		"The struct attribute post-comment with details \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.classMethodExtended2(int, int)",
+    		" The class method with parameter \n" +
+    		" \n" +
+    		" @param a Parameter a \n" +
+    		" @param b Parameter b \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeStruct",
+    		" The struct comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.doxygen_parsing.setSomeVar(int)",
+    		" The var comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.structMethod()",
+    		" The struct method comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.doxygen_parsing.someFunction()",
+    		" The function comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.classMethodExtended(int, int)",
+    		" The class method with parameter \n" +
+    		" \n" +
+    		" @param a Parameter a \n" +
+    		" @param b Parameter b \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr(int)",
+    		" The class attribute comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.structMethodExtended(int, int)",
+    		" The struct method with parameter \n" +
+    		" \n" +
+    		" @param a Parameter a \n" +
+    		" @param b Parameter b \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.getStructAttr()",
+    		" The struct attribute comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeClass",
+    		" The class comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.getStructAttr3()",
+    		"The struct attribute post-comment with details \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.doxygen_parsing.getSomeVar()",
+    		" The var comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.setStructAttr2(int)",
+    		"The struct attribute post-comment \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.getClassAttr2()",
+    		"The class attribute post-comment \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.getStructAttr2()",
+    		"The struct attribute post-comment \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.setStructAttr(int)",
+    		" The struct attribute comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeEnum",
+    		" The enum comment \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.getClassAttr3()",
+    		"The class attribute post-comment with details \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.classMethod()",
+    		" The class method comment.<br>\n" +
+                " <br>\n" +
+                " {@link SomeAnotherClass#classMethodExtended(int,int) a link text  }\n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.structMethodExtended2(int, int)",
+    		" The struct method with parameter \n" +
+    		" \n" +
+    		" @param a Parameter a \n" +
+    		" @param b Parameter b \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr2(int)",
+    		"The class attribute post-comment \n" +
+    		"");
+    
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_translate_all_tags_runme.java

@@ -0,0 +1,153 @@
+
+import doxygen_translate_all_tags.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_translate_all_tags_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_translate_all_tags");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_translate_all_tags runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_translate_all_tags"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func01(int)",
+    		" <i>Hello </i>\n\n\n" +
+                " <a id=\"theAnchor\"></a>\n\n\n" +
+    		" <li>some list item</li>\n\n" +
+    		" This is attention!\n" +
+    		" You were warned!\n" +
+    		" @author lots of them\n" +
+    		" @author Zubr\n\n" +
+    		" <b>boldword</b>\n\n" +
+    		" Some brief description,\n" +
+    		" extended to many lines.\n\n" +
+    		" Not everything works right now...\n" +
+    		" <code>codeword</code>\n\n\n\n\n\n" +
+    		" <i>citationword</i>\n" +
+                " {@code some test code }\n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func02(int)",
+    		" Conditional comment: SOMECONDITION \n" +
+    		" Some conditional comment \n" +
+    		" End of conditional comment.\n" +
+    		" Copyright: some copyright \n" +
+    		" 1970 - 2012 \n" +
+    		" @deprecated Now use another function \n" +
+    		" This is very large \n" +
+    		" and detailed description of some thing \n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func03(int)",
+                       " Comment for <b>func03()</b>.\n" +
+                       " <i>italicword </i>\n" +
+    		" <i>emphazedWord </i>\n" +
+                " @ example someFile.txt\n" +
+                " Some details on using the example");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func04(int)",
+                       " @exception SuperError \n" +
+                       " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
+                       " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
+                       " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
+    		" This will only appear in hmtl \n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func05(int)",
+                       " If: ANOTHERCONDITION {\n" +
+    		" First part of comment \n" +
+    		" If: SECONDCONDITION {\n" +
+    		" Nested condition text \n" +
+    		" }Else if: THIRDCONDITION {\n" +
+    		" The third condition text \n" +
+    		" }Else:  {The last text block \n" +
+    		" }\n" +
+    		" }Else:  {Second part of comment \n" +
+    		" If: CONDITION {\n" +
+    		" Second part extended \n" +
+    		" }\n" +
+    		" }\n" +
+    		" If not: SOMECONDITION {\n" +
+    		" This is printed if not \n" +
+    		" }\n" +
+    		" <img src=testImage.bmp alt=\"Hello, world!\" />\n" +
+    		" Some text \n" +
+    		" describing invariant. \n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func06(int)",
+                       " Comment for <b>func06()</b>.\n" +
+                       " This will only appear in LATeX \n" +
+    		" <ul> \n" +
+    		" <li>Some unordered list \n" +
+    		" </li><li>With lots of items \n" +
+    		" </li><li>lots of lots of items \n" +
+    		" </li></ul> \n" +
+    		" {@link someMember Some description follows }\n" +
+    		" This will only appear in man\n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func07(int)",
+                       " Comment for <b>func07()</b>.\n" +
+                       " Note: Here \n" +
+    		" is the note! \n" +
+    		" This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.\n" +
+    		" <code>someword </code>\n" +
+    		" @package superPackage \n" +
+    		" <p alt=\"The paragraph title \">\n" +
+    		" The paragraph text. \n" +
+    		" Maybe even multiline \n" +
+    		" </p>\n" +
+                " @param a the first param\n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func08(int)",
+                       "<a id=\"someAnchor\"></a>\n" +
+                       "Text after anchor.\n" + 
+                       "<a href=\"#someAnchor\">Anchor description</a>\n" +
+                       "<a href=\"#someAnchor\">someAnchor</a> not quoted text is not part of ref tag\n" +
+                       "<a href=\"#someAnchor\">someAnchor</a>\n" +
+                       " Remarks: Some remark text \n" +
+                       " Remarks: Another remarks section \n" +
+                       " @return Whatever \n" +
+                       " @return it \n" +
+                       " @return may return \n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func09(int)",
+                       " This will only appear in RTF \n" +
+    		" @see someOtherMethod \n" +
+    		" @see function \n" +
+    		" Same as \n" +
+    		" brief description \n" +
+    		" @since version 0.0.0.1 \n" +
+    		" @throws superException \n" +
+    		" @throws RuntimeError \n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func10(int, float)",
+                       " TODO: Some very important task \n" +
+    		" @param b B is mentioned again... \n" +
+    		" {@literal \n" +
+    		"very long \n" +
+    		"text with tags <sometag> \n" +
+    		" }\n" +
+    		" @version 0.0.0.2 \n" +
+    		" Warning: This is senseless! \n" +
+    		" This will only appear in XML \n" +
+    		" Here goes test of symbols: \n" +
+    		" $ @ \\ &amp; ~ &lt; &gt; # % &quot; . :: \n" +
+    		" And here goes simple text \n" +
+    		"");
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_translate_links_runme.java

@@ -0,0 +1,69 @@
+
+import doxygen_translate_links.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_translate_links_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_translate_links");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_translate_links runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_translate_links"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    
+    wantedComments.put("doxygen_translate_links.doxygen_translate_links.function()",
+    		" \n" +
+    		" Testing typenames converting in @ link \n" +
+    		" \n" +
+    		" {@link superFunc(int,String) \n" +
+    		" Test for std_string member \n" +
+    		" }\n" +
+    		" \n" +
+    		" {@link superFunc(int,int,SWIGTYPE_p_void) \n" +
+    		" Test for simple types \n" +
+    		" }\n" +
+    		" \n" +
+    		" {@link superFunc(SWIGTYPE_p_p_Shape) \n" +
+    		" Test for custom types \n" +
+    		" }\n" +
+    		" \n" +
+    		" {@link superFunc(SWIGTYPE_p_p_p_int) \n" +
+    		" Test for complex types \n" +
+    		" }\n" +
+    		" \n" +
+    		" same works for 'See also:' links: \n" +
+    		" \n" +
+    		" @see superFunc(int,String)\n" +
+    		" @see superFunc(int,int,SWIGTYPE_p_void)\n" +
+    		" @see superFunc(SWIGTYPE_p_p_Shape)\n" +
+    		" @see superFunc(SWIGTYPE_p_p_p_int)\n" +
+    		" \n" +
+    		" some failing params: \n" +
+    		" \n" +
+    		" @see superFunc() \n" +
+    		" @see superFunc() \n" +
+    		" @see superFunc() \n" +
+    		" \n" +
+    		" \n" +
+    		"");
+    
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_translate_runme.java

@@ -0,0 +1,279 @@
+
+import doxygen_translate.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+import java.util.Map;
+
+public class doxygen_translate_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_translate");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+  
+  public static void main(String argv[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_translate runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_translate"});
+
+    Map<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_translate.doxygen_translate.function(int, float)",
+    		" <i>Hello </i>\n" +
+    		" \n" +
+    		" <li>some list item</li>\n" +
+    		" \n" +
+    		" @author lots of them \n" +
+    		" \n" +
+    		" @author Zubr \n" +
+    		" \n" +
+    		" <b>boldword </b>\n" +
+    		" \n" +
+    		" <code>codeword </code>\n" +
+    		" \n" +
+    		" <i>citationword </i>\n" +
+    		" \n" +
+    		" {@code some test code }\n" +
+    		" \n" +
+    		" Conditional comment: SOMECONDITION \n" +
+    		" Some conditional comment \n" +
+    		" End of conditional comment.\n" +
+    		" \n" +
+    		" Copyright: some copyright \n" +
+    		" \n" +
+    		" @deprecated Now use another function \n" +
+    		" \n" +
+    		" <i>italicword </i>\n" +
+    		" \n" +
+    		" @ example someFile.txt\n" +
+    		" Some details on using the example\n" +
+    		" \n" +
+                " @exception SuperError \n" +
+    		" \n" +
+    		" If: ANOTHERCONDITION {\n" +
+    		" First part of comment \n" +
+    		" If: SECONDCONDITION {\n" +
+    		" Nested condition text}\n" +
+    		" Else if: THIRDCONDITION {\n" +
+    		" The third condition text}\n" +
+    		" Else:  {The last text block}}\n" +
+    		" \n" +
+    		" Else:  {Second part of comment \n" +
+    		" If: CONDITION {\n" +
+    		" Second part extended}}\n" +
+    		" \n" +
+    		" \n" +
+    		" \n" +
+    		" If not: SOMECONDITION {\n" +
+    		" This is printed if not}\n" +
+    		" \n" +
+    		" \n" +
+    		" <img src=testImage.bmp alt=\"Hello, world!\"/>\n" +
+    		" \n" +
+    		" <ul> \n" +
+    		" \n" +
+    		" <li>Some unordered list</li>\n" +
+    		" <li>With lots of items</li>\n" +
+    		" <li>lots of lots of items</li>\n" +
+    		" \n" +
+    		" </ul> \n" +
+    		" \n" +
+    		" {@link someMember Some description follows }\n" +
+    		" \n" +
+    		" \n" +
+    		" \n" +
+    		" \n" +
+    		" \n" +
+    		" \n" +
+    		" Note: Here \n" +
+    		" is the note! \n" +
+    		" \n" +
+    		" This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.\n" +
+    		" \n" +
+    		" <code>someword </code>\n" +
+    		" \n" +
+    		" @package superPackage \n" +
+    		" \n" +
+    		" <p alt=\"The paragraph title \">\n" +
+    		" The paragraph text. \n" +
+    		" Maybe even multiline</p>\n" +
+    		" \n" +
+    		" @param a the first param \n" +
+    		" \n" +
+    		" Remarks: Some remark text \n" +
+    		" \n" +
+    		" Remarks: Another remarks section \n" +
+    		" \n" +
+    		" @return Whatever \n" +
+    		" \n" +
+    		" @return it \n" +
+    		" \n" +
+    		" @return may return \n" +
+    		" \n" +
+    		" @see someOtherMethod \n" +
+    		" \n" +
+    		" @see function \n" +
+    		" \n" +
+    		" @since version 0.0.0.1 \n" +
+    		" \n" +
+    		" @throws superException \n" +
+    		" \n" +
+    		" @throws RuntimeError \n" +
+    		" \n" +
+    		" TODO: Some very important task \n" +
+    		" \n" +
+    		" @param b B is mentioned again... \n" +
+    		" \n" +
+    		" {@literal \n" +
+    		"very long \n" +
+    		"text with tags <sometag> \n" +
+    		" }\n" +
+    		" \n" +
+    		" @version 0.0.0.2 \n" +
+    		" \n" +
+    		" Warning: This is senseless! \n" +
+    		" \n" +
+    		" Here goes test of symbols: \n" +
+    		" $ @ \\ &amp; ~ &lt; &gt; # % &quot; . :: \n" +
+    		" \n" +
+    		" And here goes simple text \n" +
+    		" \n" +
+    		"");
+
+        wantedComments.put("doxygen_translate.doxygen_translate.htmlFunction(int, float)",
+    		" Test for html tags. See Doxygen doc for list of tags recognized by Doxygen.          \n" +
+    		"                                                                                      \n" +
+    		" <a href=\"http://acme.com/index.html\">This is link</a>                               \n" +
+    		" <b>bold</b>                                                                          \n" +
+    		" <blockquote cite=\"http://www.worldwildlife.org/who/index.html\">                                                                         \n" +
+    		" Quotation block.                                                                     \n" +
+    		" </blockquote>                                                                        \n" +
+    		" <br>                                                                                 \n" +
+    		" <center>center</center>                                                              \n" +
+    		" <code>this is code</code>                                                            \n" +
+                "\n" + 
+    		"  <dl>\n" + 
+    		"  <dt>Starts an item title.</dt>\n" + 
+    		"  <dd>Starts an item description.</dd>\n" + 
+    		"  </dl>\n" +
+                "\n" + 
+    		" <dfn> Starts a piece of text displayed in a typewriter font.                         \n" +
+    		" </dfn>                                                                               \n" +
+    		" <div> Starts a section with a specific style (HTML only)                             \n" +
+    		" </div>                                                                               \n" +
+    		" <em> Starts a piece of text displayed in an italic font.</em>                        \n" +
+    		"\n" +
+    		" <form> 'Form' does not generate any output.                                          \n" +
+    		" </form>                                                                              \n" +
+    		" <hr>                                                                                 \n" +
+    		" <h1> Heading 1                                                   \n" +
+    		" </h1>                                                                                \n" +
+    		" <h2> Heading 2                                                \n" +
+    		" </h2>                                                                                \n" +
+    		" <h3> Heading 3                                             \n" +
+    		" </h3>                                                                                \n" +
+    		" <i>Starts a piece of text displayed in an italic font.</i>                              \n" +
+    		" <input>Input tag.                                                \n" +
+    		"                                                                                  \n" +
+    		" <img src=\"slika.png\">                                                                \n" +
+    		" <meta>Meta tag.                                                 \n" +
+    		" <multicol>Multicol is ignored by doxygen.                                                       \n" +
+    		" </multicol>                                                      \n" +
+    		"                                                                                      \n" +
+    		" <ol>                                                      \n" +
+    		" <li>List item 1.</li>                                                      \n" +
+    		" <li>List item 2.</li>                                                      \n" +
+    		" </ol>                                                       \n" +
+    		"                                                                                      \n" +
+    		" <p> Starts a new paragraph.                                                          \n" +
+    		" </p>                                                                                 \n" +
+    		" <pre> Starts a preformatted fragment.                                                \n" +
+    		" </pre>                                                                               \n" +
+    		" <small> Starts a section of text displayed in a smaller font.                        \n" +
+    		" </small>                                                                             \n" +
+    		" <span> Starts an inline text fragment with a specific style.</span>              \n" +
+    		"                                                                               \n" +
+    		" <strong> Starts a section of bold text.</strong>                                              \n" +
+    		" <sub> Starts a piece of text displayed in subscript.</sub>                                 \n" +
+    		" <sup> Starts a piece of text displayed in superscript.</sup>                               \n" +
+    		"                                                                                      \n" +
+    		" <table border = '1'>                                                                 \n" +
+    		" <caption>Animals</caption>                                                           \n" +
+    		" <tr><th> Column 1   </th><th> Column 2   </th></tr>                                           \n" +
+    		" <tr><td> cow   </td><td> dog    </td></tr>                                           \n" +
+    		" <tr><td> cat   </td><td> mouse  </td></tr>                                           \n" +
+    		" <tr><td> horse </td><td> parrot </td></tr>                                           \n" +
+    		" </table>                                                                             \n" +
+    		"                                                                                      \n" +
+    		" <tt> Starts a piece of text displayed in a typewriter font.                          \n" +
+    		" </tt>                                                                                \n" +
+    		" <kbd> Starts a piece of text displayed in a typewriter font.                         \n" +
+    		" </kbd>                                                                               \n" +
+    		"                                                                                      \n" +
+    		"  <ul>\n" +
+    		"  <li>List item 1.</li>\n" +
+    		"  <li>List item 2.</li>\n" +
+    		"  <li>List item 3.</li>\n" +
+    		"  </ul>\n" +
+    		"                                                                                      \n" +
+    		" <var> Starts a piece of text displayed in an italic font.</var>                            \n" +
+    		"                                                                                \n" +
+                "\n" +
+                "<u>underlined \\b bold text - doxy commands are ignored inside 'htmlonly' section </u>\n" +
+                "\n" +
+                "");
+
+        wantedComments.put("doxygen_translate.doxygen_translate.htmlTableFunction(int)",
+                "The meaning of flags:\n" +
+                "\n" +
+                " @param byFlags bits marking required items:\n" +
+                "   <table>\n" +
+                "   <tr><th> Size in bits</th><th> Items Required </th></tr>\n" +
+                "   <tr><td> 1 - 8       </td><td>      1         </td></tr>\n" +
+                "   <tr><td> 9 - 16      </td><td>      2         </td></tr>\n" +
+                "   <tr><td> 17 - 32     </td><td>      4         </td></tr>\n" +
+                "   </table>\n" +
+                "   Almost all combinations of above flags are supported by\n" +
+                "   <code>htmlTable...</code> functions.\n" +
+                   "");
+
+        
+        wantedComments.put("doxygen_translate.doxygen_translate.htmlEntitiesFunction(int, float)",
+                "All entities are treated as commands &copy; &trade; &reg;\n" +
+                "should work also&lt;in text                              \n" +
+                "&gt;                                                     \n" +
+                "&amp;                                                    \n" +
+                "&apos;                                                   \n" +
+                "&quot;                                                   \n" +
+                "&lsquo;                                                  \n" +
+                "&rsquo;                                                  \n" +
+                "&ldquo;                                                  \n" +
+                "&rdquo;                                                  \n" +
+                "&ndash;                                                  \n" +
+                "&mdash;                                                  \n" +
+                "&nbsp;                                                   \n" +
+                "&times;                                                  \n" +
+                "&minus;                                                  \n" +
+                "&sdot;                                                   \n" +
+                "&sim;                                                    \n" +
+                "&le;                                                     \n" +
+                "&ge;                                                     \n" +
+                "&larr;                                                   \n" +
+                "&rarr;                                                   \n" +
+                "Not an  html entity - ignored by Doxygen.                \n" +
+                "Not an &amp;text html entity - ampersand is replaced with entity.\n" +
+                "");
+        
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/python/autodoc_runme.py

@@ -1,16 +1,14 @@
 from autodoc import *
+import comment_verifier
+import inspect
 import sys
 
-
 def check(got, expected, expected_builtin=None, skip=False):
     if not skip:
         expect = expected
         if is_python_builtin() and expected_builtin != None:
             expect = expected_builtin
-        if expect != got:
-            raise RuntimeError(
-                "\n" + "Expected: [" + str(expect) + "]\n" + "Got     : [" + str(got) + "]")
-
+        comment_verifier.check(got, expect)
 
 def is_new_style_class(cls):
     return hasattr(cls, "__class__")
@@ -31,97 +29,35 @@ if is_fastproxy(dir()):
 # skip builtin check - the autodoc is missing, but it probably should not be
 skip = True
 
-check(A.__doc__, "Proxy of C++ A class.", "::A")
-check(A.funk.__doc__, "just a string.")
-check(A.func0.__doc__,
-      "func0(self, arg2, hello) -> int",
-      "func0(arg2, hello) -> int")
-check(A.func1.__doc__,
-      "func1(A self, short arg2, Tuple hello) -> int",
-      "func1(short arg2, Tuple hello) -> int")
-check(A.func2.__doc__,
-      "\n"
-      "        func2(self, arg2, hello) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        arg2: short\n"
-      "        hello: int tuple[2]\n"
-      "\n"
-      "        ",
-      "\n"
-      "func2(arg2, hello) -> int\n"
+check(inspect.getdoc(A), "Proxy of C++ A class.", "::A")
+check(inspect.getdoc(A.funk), "just a string.")
+check(inspect.getdoc(A.func0),
+      "func0(self, arg2, hello) -> int")
+check(inspect.getdoc(A.func1),
+      "func1(A self, short arg2, Tuple hello) -> int")
+check(inspect.getdoc(A.func2),
+      "func2(self, arg2, hello) -> int\n"
       "\n"
       "Parameters\n"
       "----------\n"
       "arg2: short\n"
-      "hello: int tuple[2]\n"
-      "\n"
-      ""
-      )
-check(A.func3.__doc__,
-      "\n"
-      "        func3(A self, short arg2, Tuple hello) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        arg2: short\n"
-      "        hello: int tuple[2]\n"
-      "\n"
-      "        ",
-      "\n"
-      "func3(short arg2, Tuple hello) -> int\n"
+      "hello: int tuple[2]")
+check(inspect.getdoc(A.func3),
+      "func3(A self, short arg2, Tuple hello) -> int\n"
       "\n"
       "Parameters\n"
       "----------\n"
       "arg2: short\n"
-      "hello: int tuple[2]\n"
-      "\n"
-      ""
-      )
+      "hello: int tuple[2]")
 
-check(A.func0default.__doc__,
-      "\n"
-      "        func0default(self, e, arg3, hello, f=2) -> int\n"
-      "        func0default(self, e, arg3, hello) -> int\n"
-      "        ",
-      "\n"
-      "func0default(e, arg3, hello, f=2) -> int\n"
-      "func0default(e, arg3, hello) -> int\n"
-      ""
-      )
-check(A.func1default.__doc__,
-      "\n"
-      "        func1default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n"
-      "        func1default(A self, A e, short arg3, Tuple hello) -> int\n"
-      "        ",
-      "\n"
-      "func1default(A e, short arg3, Tuple hello, double f=2) -> int\n"
-      "func1default(A e, short arg3, Tuple hello) -> int\n"
-      ""
-      )
-check(A.func2default.__doc__,
-      "\n"
-      "        func2default(self, e, arg3, hello, f=2) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        e: A *\n"
-      "        arg3: short\n"
-      "        hello: int tuple[2]\n"
-      "        f: double\n"
-      "\n"
-      "        func2default(self, e, arg3, hello) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        e: A *\n"
-      "        arg3: short\n"
-      "        hello: int tuple[2]\n"
-      "\n"
-      "        ",
-      "\n"
-      "func2default(e, arg3, hello, f=2) -> int\n"
+check(inspect.getdoc(A.func0default),
+      "func0default(self, e, arg3, hello, f=2) -> int\n"
+      "func0default(self, e, arg3, hello) -> int")
+check(inspect.getdoc(A.func1default),
+      "func1default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n"
+      "func1default(A self, A e, short arg3, Tuple hello) -> int")
+check(inspect.getdoc(A.func2default),
+      "func2default(self, e, arg3, hello, f=2) -> int\n"
       "\n"
       "Parameters\n"
       "----------\n"
@@ -130,38 +66,15 @@ check(A.func2default.__doc__,
       "hello: int tuple[2]\n"
       "f: double\n"
       "\n"
-      "func2default(e, arg3, hello) -> int\n"
+      "func2default(self, e, arg3, hello) -> int\n"
       "\n"
       "Parameters\n"
       "----------\n"
       "e: A *\n"
       "arg3: short\n"
-      "hello: int tuple[2]\n"
-      "\n"
-      ""
-      )
-check(A.func3default.__doc__,
-      "\n"
-      "        func3default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        e: A *\n"
-      "        arg3: short\n"
-      "        hello: int tuple[2]\n"
-      "        f: double\n"
-      "\n"
-      "        func3default(A self, A e, short arg3, Tuple hello) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        e: A *\n"
-      "        arg3: short\n"
-      "        hello: int tuple[2]\n"
-      "\n"
-      "        ",
-      "\n"
-      "func3default(A e, short arg3, Tuple hello, double f=2) -> int\n"
+      "hello: int tuple[2]")
+check(inspect.getdoc(A.func3default),
+      "func3default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n"
       "\n"
       "Parameters\n"
       "----------\n"
@@ -170,58 +83,21 @@ check(A.func3default.__doc__,
       "hello: int tuple[2]\n"
       "f: double\n"
       "\n"
-      "func3default(A e, short arg3, Tuple hello) -> int\n"
+      "func3default(A self, A e, short arg3, Tuple hello) -> int\n"
       "\n"
       "Parameters\n"
       "----------\n"
       "e: A *\n"
       "arg3: short\n"
-      "hello: int tuple[2]\n"
-      "\n"
-      ""
-      )
+      "hello: int tuple[2]")
 
-check(A.func0static.__doc__,
-      "\n"
-      "        func0static(e, arg2, hello, f=2) -> int\n"
-      "        func0static(e, arg2, hello) -> int\n"
-      "        ",
-      "\n"
+check(inspect.getdoc(A.func0static),
       "func0static(e, arg2, hello, f=2) -> int\n"
-      "func0static(e, arg2, hello) -> int\n"
-      ""
-      )
-check(A.func1static.__doc__,
-      "\n"
-      "        func1static(A e, short arg2, Tuple hello, double f=2) -> int\n"
-      "        func1static(A e, short arg2, Tuple hello) -> int\n"
-      "        ",
-      "\n"
+      "func0static(e, arg2, hello) -> int")
+check(inspect.getdoc(A.func1static),
       "func1static(A e, short arg2, Tuple hello, double f=2) -> int\n"
-      "func1static(A e, short arg2, Tuple hello) -> int\n"
-      ""
-      )
-check(A.func2static.__doc__,
-      "\n"
-      "        func2static(e, arg2, hello, f=2) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        e: A *\n"
-      "        arg2: short\n"
-      "        hello: int tuple[2]\n"
-      "        f: double\n"
-      "\n"
-      "        func2static(e, arg2, hello) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        e: A *\n"
-      "        arg2: short\n"
-      "        hello: int tuple[2]\n"
-      "\n"
-      "        ",
-      "\n"
+      "func1static(A e, short arg2, Tuple hello) -> int")
+check(inspect.getdoc(A.func2static),
       "func2static(e, arg2, hello, f=2) -> int\n"
       "\n"
       "Parameters\n"
@@ -237,31 +113,8 @@ check(A.func2static.__doc__,
       "----------\n"
       "e: A *\n"
       "arg2: short\n"
-      "hello: int tuple[2]\n"
-      "\n"
-      ""
-      )
-check(A.func3static.__doc__,
-      "\n"
-      "        func3static(A e, short arg2, Tuple hello, double f=2) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        e: A *\n"
-      "        arg2: short\n"
-      "        hello: int tuple[2]\n"
-      "        f: double\n"
-      "\n"
-      "        func3static(A e, short arg2, Tuple hello) -> int\n"
-      "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        e: A *\n"
-      "        arg2: short\n"
-      "        hello: int tuple[2]\n"
-      "\n"
-      "        ",
-      "\n"
+      "hello: int tuple[2]")
+check(inspect.getdoc(A.func3static),
       "func3static(A e, short arg2, Tuple hello, double f=2) -> int\n"
       "\n"
       "Parameters\n"
@@ -277,97 +130,78 @@ check(A.func3static.__doc__,
       "----------\n"
       "e: A *\n"
       "arg2: short\n"
-      "hello: int tuple[2]\n"
-      "\n"
-      ""
-      )
+      "hello: int tuple[2]")
 
 if sys.version_info[0:2] > (2, 4):
     # Python 2.4 does not seem to work
-    check(A.variable_a.__doc__,
+    check(inspect.getdoc(A.variable_a),
           "A_variable_a_get(self) -> int",
           "A.variable_a"
           )
-    check(A.variable_b.__doc__,
+    check(inspect.getdoc(A.variable_b),
           "A_variable_b_get(A self) -> int",
           "A.variable_b"
           )
-    check(A.variable_c.__doc__,
-          "\n"
+    check(inspect.getdoc(A.variable_c),
           "A_variable_c_get(self) -> int\n"
           "\n"
           "Parameters\n"
           "----------\n"
-          "self: A *\n"
-          "\n",
+          "self: A *",
           "A.variable_c"
-          )
-    check(A.variable_d.__doc__,
-          "\n"
+        )
+    check(inspect.getdoc(A.variable_d),
           "A_variable_d_get(A self) -> int\n"
           "\n"
           "Parameters\n"
           "----------\n"
-          "self: A *\n"
-          "\n",
+          "self: A *",
           "A.variable_d"
-          )
+        )
 
-check(B.__doc__,
+check(inspect.getdoc(B),
       "Proxy of C++ B class.",
       "::B"
       )
-check(C.__init__.__doc__, "__init__(self, a, b, h) -> C", None, skip)
-check(D.__init__.__doc__,
+check(inspect.getdoc(C.__init__), "__init__(self, a, b, h) -> C", None, skip)
+check(inspect.getdoc(D.__init__),
       "__init__(D self, int a, int b, Hola h) -> D", None, skip)
-check(E.__init__.__doc__,
+check(inspect.getdoc(E.__init__),
+      "__init__(self, a, b, h) -> E\n"
       "\n"
-      "        __init__(self, a, b, h) -> E\n"
+      "__init__(self, a, b, h) -> E\n"
       "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        a: special comment for parameter a\n"
-      "        b: another special comment for parameter b\n"
-      "        h: enum Hola\n"
-      "\n"
-      "        ", None, skip
+      "Parameters\n"
+      "----------\n"
+      "a: special comment for parameter a\n"
+      "b: another special comment for parameter b\n"
+      "h: enum Hola", None, skip
       )
-check(F.__init__.__doc__,
+check(inspect.getdoc(F.__init__),
+      "__init__(F self, int a, int b, Hola h) -> F\n"
       "\n"
-      "        __init__(F self, int a, int b, Hola h) -> F\n"
+      "__init__(F self, int a, int b, Hola h) -> F\n"
       "\n"
-      "        Parameters\n"
-      "        ----------\n"
-      "        a: special comment for parameter a\n"
-      "        b: another special comment for parameter b\n"
-      "        h: enum Hola\n"
-      "\n"
-      "        ", None, skip
+      "Parameters\n"
+      "----------\n"
+      "a: special comment for parameter a\n"
+      "b: another special comment for parameter b\n"
+      "h: enum Hola", None, skip
       )
 
-check(B.funk.__doc__,
-      "funk(B self, int c, int d) -> int",
-      "funk(int c, int d) -> int")
-check(funk.__doc__, "funk(A e, short arg2, int c, int d) -> int")
-check(funkdefaults.__doc__,
-      "\n"
-      "    funkdefaults(A e, short arg2, int c, int d, double f=2) -> int\n"
-      "    funkdefaults(A e, short arg2, int c, int d) -> int\n"
-      "    ",
-      "\n"
+check(inspect.getdoc(B.funk),
+      "funk(B self, int c, int d) -> int")
+check(inspect.getdoc(funk), "funk(A e, short arg2, int c, int d) -> int")
+check(inspect.getdoc(funkdefaults),
       "funkdefaults(A e, short arg2, int c, int d, double f=2) -> int\n"
-      "funkdefaults(A e, short arg2, int c, int d) -> int\n"
-      ""
-      )
+      "funkdefaults(A e, short arg2, int c, int d) -> int")
 
-check(func_input.__doc__, "func_input(int * INPUT) -> int")
-check(func_output.__doc__, "func_output() -> int")
-check(func_inout.__doc__, "func_inout(int * INOUT) -> int")
-check(func_cb.__doc__, "func_cb(int c, int d) -> int")
-check(banana.__doc__, "banana(S a, S b, int c, Integer d)")
+check(inspect.getdoc(func_input), "func_input(int * INPUT) -> int")
+check(inspect.getdoc(func_output), "func_output() -> int")
+check(inspect.getdoc(func_inout), "func_inout(int * INOUT) -> int")
+check(inspect.getdoc(func_cb), "func_cb(int c, int d) -> int")
+check(inspect.getdoc(banana), "banana(S a, S b, int c, Integer d)")
 
-check(TInteger.__doc__, "Proxy of C++ T< int > class.", "::T< int >")
-check(TInteger.__init__.__doc__, "__init__(TInteger self) -> TInteger", None, skip)
-check(TInteger.inout.__doc__,
-      "inout(TInteger self, TInteger t) -> TInteger",
-      "inout(TInteger t) -> TInteger")
+check(inspect.getdoc(TInteger), "Proxy of C++ T< int > class.", "::T< int >")
+check(inspect.getdoc(TInteger.__init__), "__init__(TInteger self) -> TInteger", None, skip)
+check(inspect.getdoc(TInteger.inout), "inout(TInteger self, TInteger t) -> TInteger")

Examples/test-suite/python/comment_verifier.py

@@ -0,0 +1,26 @@
+def check(got, expected, expected_builtin=None):
+  if got is None:  # Absence of comment is equivalent to empty comment.
+      got = ''
+
+  if got != expected:
+    import re
+    p = re.compile(r'^[+-]([^+-].*\S)?(\s+)$', re.M)
+
+    def make_trailing_spaces_visible(str):
+        def replace_trailing_spaces(match):
+            res = match.group(0)
+            spaces = match.group(2)
+            if spaces is not None:
+                res = res + "{+%d trailing spaces}" % len(spaces)
+            return res
+        return re.sub(p, replace_trailing_spaces, str)
+
+    from difflib import unified_diff
+    diff = unified_diff(expected.splitlines(True),
+                        got.splitlines(True), "expected", "got")
+    lines = []
+    for line in diff:
+        line = make_trailing_spaces_visible(line.strip("\r\n"))
+        lines.append(line + "\n")
+
+    raise RuntimeError("Comments don't match:\n" + "".join(lines))

Examples/test-suite/python/doxygen_alias_runme.py

@@ -0,0 +1,10 @@
+import doxygen_alias
+import inspect
+import comment_verifier
+
+comment_verifier.check(inspect.getdoc(doxygen_alias.make_something),
+    """\
+A function returning something.
+
+:rtype: :py:class:`Something`
+:return: A new object which may be None.""")

Examples/test-suite/python/doxygen_basic_notranslate_runme.py

@@ -0,0 +1,63 @@
+import doxygen_basic_notranslate
+import inspect
+import string
+import sys
+import comment_verifier
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function),
+    r"""\brief
+Brief description.
+
+The comment text
+\author Some author
+\return Some number
+\sa function2"""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function2),
+    r"""A test of a very very very very very very very very very very very very very very very very
+very very very very very long comment string."""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function3),
+    r"""*Overload 1:*
+
+A test for overloaded functions
+This is function \b one
+
+|
+
+*Overload 2:*
+
+A test for overloaded functions
+This is function \b two"""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function4),
+    r"""A test of some mixed tag usage
+\if CONDITION
+This \a code fragment shows us something \.
+\par Minuses:
+\arg it's senseless
+\arg it's stupid
+\arg it's null
+
+\warning This may not work as expected
+
+\code
+int main() { while(true); }
+\endcode
+\endif"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function5),
+    r"""This is a post comment. """
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function6),
+    r"""Test for default args
+@param a Some parameter, default is 42"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function7),
+    r"""Test for a parameter with difficult type
+(mostly for python)
+@param a Very strange param"""
+)

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -0,0 +1,84 @@
+import doxygen_basic_translate
+import inspect
+import string
+import sys
+import comment_verifier
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function),
+    """\
+Brief description.
+
+The comment text.
+
+Author: Some author
+
+:rtype: int
+:return: Some number
+
+See also: function2"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function2),
+    """\
+A test of a very very very very very very very very very very very very very very very very
+very very very very very long comment string."""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function3),
+    """*Overload 1:*
+
+A test for overloaded functions
+This is function **one**
+
+|
+
+*Overload 2:*
+
+A test for overloaded functions
+This is function **two**"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function4),
+    """\
+A test of some mixed tag usage
+If: CONDITION {
+This *code* fragment shows us something .
+Title: Minuses:
+* it\'s senseless
+* it\'s stupid
+* it\'s null
+
+Warning: This may not work as expected
+
+.. code-block:: c++
+
+
+    int main() { while(true); }
+
+}"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function5),
+    """This is a post comment."""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function6),
+    """\
+Test for default args
+:type a: int
+:param a: Some parameter, default is 42"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function7),
+    """\
+Test for a parameter with difficult type
+(mostly for python)
+:type a: :py:class:`Shape`
+:param a: Very strange param"""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate.Atan2),
+    """\
+Multiple parameters test.
+
+:type y: float
+:param y: Vertical coordinate.
+:type x: float
+:param x: Horizontal coordinate.
+:rtype: float
+:return: Arc tangent of ``y/x``."""
+)

Examples/test-suite/python/doxygen_ignore_runme.py

@@ -0,0 +1,17 @@
+import doxygen_ignore
+import inspect
+import comment_verifier
+
+comment_verifier.check(inspect.getdoc(doxygen_ignore.func),
+    """\
+A contrived example of ignoring too many commands in one comment.
+
+
+
+
+
+
+This is specific to **Python**.
+
+
+Command ignored, but anything here is still included.""")

Examples/test-suite/python/doxygen_misc_constructs_runme.py

@@ -0,0 +1,133 @@
+import doxygen_misc_constructs
+import inspect
+import string
+import sys
+import comment_verifier
+
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.getAddress),
+    r"""Returns address of file line.
+
+:type fileName: int
+:param fileName: name of the file, where the source line is located
+:type line: int
+:param line: line number
+:type isGetSize: boolean
+:param isGetSize: if set, for every object location both address and size are returned
+
+Connection::getId() """)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.CConnectionConfig),
+    r"""This class contains information for connection to winIDEA. Its methods
+return reference to self, so we can use it like this:
+
+CConnectionConfig config = new CConnectionConfig();
+config.discoveryPort(5534).dllPath("C:\\myWinIDEA\\connect.dll").id("main");
+
+
+All parameters are optional. Set only what is required, default values are
+used for unspecified parameters.
+
+
+
+advancedWinIDEALaunching.py Python example.""")
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.waitTime),
+    r"""Determines how long the ``isystem.connect`` should wait for running
+instances to respond. Only one of ``lfWaitXXX`` flags from IConnect::ELaunchFlags
+may be specified."""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.getConnection),
+    r"""This function returns connection id."""
+)
+
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.getFirstLetter),
+    r''
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.ClassWithNestedEnum),
+    r"""Class description."""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.showList),
+    r"""An example of a list in a documentation comment.
+
+    - The first item of the list.
+    - The second list item, on
+      several indented lines,
+      showing that the indentation
+      is preserved.
+    - And the final list item after it.
+
+And this is not a list item any more."""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidA),
+    r"""This comment without space after '*' is valid in Doxygen."""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidB),
+    r""".This comment without space after '*' is valid in Doxygen."""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidC),
+    r''
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.backslashA),
+    r"""Backslash following``word`` is a valid doxygen command. Output contains
+'followingword' with 'word' in code font."""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.backslashB),
+    r"""Doxy command without trailing space is ignored - nothing appears
+on output. Standalone \ and '\' get to output.
+Standalone @ and '@' get to output.
+Commands "in quoted \b strings are treated as plain text".
+Commands not recognized by Doxygen are ignored.
+Backslashes in DOS paths d:and words
+following them do not appear on output, we must quote them with
+double quotes: "d:\xyz\qwe\myfile", "@something". Single quotes do not help:
+'d:'. Escaping works: d:\xyz\qwe\myfile. Unix
+paths of course have no such problems: /xyz/qwe/myfile
+Commands for escaped symbols:
+$ @ \ & ~ < > # % " . :: @text ::text"""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.backslashC),
+    r"""Backslash e at end of *line* froze SWIG
+*with* old comment parser.
+
+See also: MyClass::fun(char,
+ float)"""
+)
+
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.cycle),
+    r"""The next line contains expression:
+
+['retVal < 10', 'g_counter == 23 && g_mode & 3']
+
+
+Both words should be emphasized **isystem.connect**.
+But not the last period. For **example**, comma should not be emphasized.
+Similar **for**: double colon.
+
+Spaces at the start of line should be taken into account:
+:type id: int
+:param id: used as prefix in log
+        statements. The default value is empty string, which is OK if
+        there is only one app. instance. Example:
+
+            ctrl.setBP("func1");
+
+        If we set the id to ``main_``, we get:
+
+            main_ctrl.setBP("func1");
+
+
+:type fileName: string
+:param fileName: name of the log file"""
+);

Examples/test-suite/python/doxygen_parsing_runme.py

@@ -0,0 +1,64 @@
+import doxygen_parsing
+import inspect
+import string
+import os
+import sys
+import comment_verifier
+
+comment_verifier.check(inspect.getdoc(doxygen_parsing.someFunction),
+    "The function comment")
+comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeClass),
+    "The class comment")
+comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeStruct),
+    "The struct comment")
+
+# There doesn't seem to be any way to specify the doc string for __init__ when
+# using "-builtin" (see http://stackoverflow.com/q/11913492/15275), so skip
+# this test in this case.
+if str(os.environ.get('SWIG_FEATURES')).find('-builtin') == -1:
+    comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.__init__),
+    r"""*Overload 1:*
+First overloaded constructor.
+
+|
+
+*Overload 2:*
+Second overloaded constructor.""")
+
+comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethod),
+    r"""The class method comment.
+
+SomeAnotherClass#classMethodExtended(int, int) a link text""")
+comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethodExtended),
+    r"""The class method with parameter
+
+:type a: int
+:param a: Parameter a
+:type b: int
+:param b: Parameter b"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethodExtended2),
+    r"""The class method with parameter
+
+:type a: int
+:param a: Parameter a
+:type b: int
+:param b: Parameter b"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethod),
+    r"""The struct method comment""")
+comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethodExtended),
+    r"""The struct method with parameter
+
+:type a: int
+:param a: Parameter a
+:type b: int
+:param b: Parameter b"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethodExtended2),
+    r"""The struct method with parameter
+
+:type a: int
+:param a: Parameter a
+:type b: int
+:param b: Parameter b""")

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -0,0 +1,306 @@
+import doxygen_translate_all_tags
+import inspect
+import string
+import sys
+import comment_verifier
+
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func01),
+r"""*Hello*
+
+
+
+
+
+* some list item
+
+This is attention!
+You were warned!
+
+Authors: lots of them
+Author: Zubr
+
+**boldword**
+
+Some brief description,
+extended to many lines.
+
+Not everything works right now...
+``codeword``
+
+
+
+
+
+'citationword'
+
+
+.. code-block:: c++
+
+     some test code""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func02),
+r"""Conditional comment: SOMECONDITION
+Some conditional comment
+End of conditional comment.
+
+
+
+
+
+
+
+Copyright: some copyright
+
+1970 - 2012
+
+
+
+
+
+Deprecated: Now use another function
+
+This is very large
+and detailed description of some thing""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func03),
+r"""Comment for **func03()**.
+
+
+
+
+
+
+
+
+
+*italicword*
+
+emphazedWord
+
+
+
+Example: someFile.txt
+Some details on using the example""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func04),
+r""":raises: SuperError
+
+
+
+:math:`\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}`
+
+
+.. math::
+
+    \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
+
+
+
+.. math::
+
+    \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
+
+
+
+
+
+
+
+
+
+
+
+
+This will only appear in hmtl""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func05),
+r"""If: ANOTHERCONDITION {
+  First part of comment
+  If: SECONDCONDITION {
+    Nested condition text
+  }Else if: THIRDCONDITION {
+    The third condition text
+  }Else:  {    The last text block
+  }
+}Else:  {  Second part of comment
+  If: CONDITION {
+    Second part extended
+  }
+}
+
+If not: SOMECONDITION {
+  This is printed if not
+}
+
+Image: testImage.bmp("Hello, world!")
+
+
+
+
+
+
+
+
+
+
+
+Some text
+describing invariant.""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func06),
+r"""Comment for **func06()**.
+
+
+
+
+This will only appear in LATeX
+
+
+
+
+* Some unordered list
+* With lots of items
+* lots of lots of items
+
+
+
+
+someMember Some description follows
+
+
+
+
+This will only appear in man""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func07),
+r"""Comment for **func07()**.
+
+
+
+
+
+
+Notes: Here
+is the note!
+
+This is an overloaded member function, provided for convenience.
+It differs from the above function only in what argument(s) it accepts.
+
+someword
+
+
+
+
+
+Title: The paragraph title
+The paragraph text.
+Maybe even multiline
+
+
+
+:type a: int
+:param a: the first param""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func08),
+r"""Text after anchor.
+
+
+
+
+
+
+'Anchor description'
+
+'someAnchor' not quoted text is not part of ref tag
+
+'someAnchor'
+
+
+
+
+
+
+
+
+
+Remarks: Some remark text
+
+Another remarks section
+
+:rtype: void
+:return: Whatever
+
+:rtype: void
+:return: it
+
+:rtype: void
+:return: may return""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func09),
+r"""This will only appear in RTF
+
+
+See also: someOtherMethod
+
+
+
+See also: function
+
+Same as
+brief description
+
+
+
+Since: version 0.0.0.1
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+:raises: superException
+
+:raises: RuntimeError""")
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func10),
+r"""TODO: Some very important task
+
+:type b: float
+:param b: B is mentioned again...
+
+
+
+
+
+
+
+very long
+text with tags <sometag>
+
+
+
+
+Version: 0.0.0.2
+
+Warning: This is senseless!
+
+
+
+
+This will only appear in XML
+
+
+Here goes test of symbols:
+$ @ \ & ~ < > # % " . ::
+
+And here goes simple text""")

Examples/test-suite/python/doxygen_translate_links_runme.py

@@ -0,0 +1,38 @@
+import doxygen_translate_links
+import inspect
+import string
+import sys
+import comment_verifier
+
+
+comment_verifier.check(inspect.getdoc(doxygen_translate_links.function),
+r"""Testing typenames converting in @ link
+
+superFunc(int,std::string)
+Test for std_string member
+
+
+superFunc(int,long,void*)
+Test for simple types
+
+
+superFunc(Shape::superType*)
+Test for custom types
+
+
+superFunc(int**[13])
+Test for complex types
+
+
+same works for 'See also:' links:
+
+See also: superFunc(int,std::string)
+See also: superFunc(int,long,void*)
+See also: superFunc(Shape::superType*)
+See also: superFunc(int**[13])
+
+some failing params:
+
+See also: superFunc()
+See also: superFunc()
+See also: superFunc()""")

Examples/test-suite/python/doxygen_translate_runme.py

@@ -0,0 +1,264 @@
+import doxygen_translate
+import inspect
+import string
+import sys
+import comment_verifier
+
+
+comment_verifier.check(inspect.getdoc(doxygen_translate.function),
+r"""*Hello*
+
+* some list item
+
+Authors: lots of them
+
+Author: Zubr
+
+**boldword**
+
+``codeword``
+
+'citationword'
+
+
+.. code-block:: c++
+
+     some test code
+
+
+Conditional comment: SOMECONDITION
+Some conditional comment
+End of conditional comment.
+
+Copyright: some copyright
+
+Deprecated: Now use another function
+
+*italicword*
+
+Example: someFile.txt
+Some details on using the example
+
+:raises: SuperError
+
+If: ANOTHERCONDITION {
+  First part of comment
+  If: SECONDCONDITION {
+    Nested condition text
+  }Else if: THIRDCONDITION {
+    The third condition text
+  }Else:  {    The last text block
+  }
+}Else:  {  Second part of comment
+  If: CONDITION {
+    Second part extended
+  }
+}
+
+If not: SOMECONDITION {
+  This is printed if not
+}
+
+Image: testImage.bmp("Hello, world!")
+
+
+
+* Some unordered list
+* With lots of items
+* lots of lots of items
+
+
+
+someMember Some description follows
+
+
+
+
+
+
+Notes: Here
+is the note!
+
+This is an overloaded member function, provided for convenience.
+It differs from the above function only in what argument(s) it accepts.
+
+someword
+
+
+
+Title: The paragraph title
+The paragraph text.
+Maybe even multiline
+
+:type a: int
+:param a: the first param
+
+Remarks: Some remark text
+
+Another remarks section
+
+:rtype: int
+:return: Whatever
+
+:rtype: int
+:return: it
+
+:rtype: int
+:return: may return
+
+See also: someOtherMethod
+
+See also: function
+
+Since: version 0.0.0.1
+
+:raises: superException
+
+:raises: RuntimeError
+
+TODO: Some very important task
+
+:type b: float
+:param b: B is mentioned again...
+
+
+very long
+text with tags <sometag>
+
+
+Version: 0.0.0.2
+
+Warning: This is senseless!
+
+Here goes test of symbols:
+$ @ \ & ~ < > # % " . ::
+
+And here goes simple text"""
+)
+
+
+
+comment_verifier.check(inspect.getdoc(doxygen_translate.htmlFunction),
+r"""Test for html tags. See Doxygen doc for list of tags recognized by Doxygen.
+
+This is link ("http://acme.com/index.html")
+**bold**
+Quote:
+Quotation block.
+ ("http://www.worldwildlife.org/who/index.html")
+
+
+center
+``this is code``
+
+
+Starts an item title.
+    Starts an item description.
+
+
+Starts a piece of text displayed in a typewriter font.
+
+Starts a section with a specific style (HTML only)
+
+**Starts a piece of text displayed in an italic font.**
+
+'Form' does not generate any output.
+
+--------------------------------------------------------------------
+
+# Heading 1
+
+## Heading 2
+
+### Heading 3
+
+*Starts a piece of text displayed in an italic font.*
+Input tag.
+Image: src="slika.png"
+Meta tag.
+Multicol is ignored by doxygen.
+
+
+
+* List item 1.
+* List item 2.
+
+
+
+Starts a new paragraph.
+
+Starts a preformatted fragment.
+
+Starts a section of text displayed in a smaller font.
+
+'Starts an inline text fragment with a specific style.'
+**Starts a section of bold text.**
+ Starts a piece of text displayed in subscript.
+ Starts a piece of text displayed in superscript.
+
+
+Animals
+| Column 1 | Column 2 |
+-----------------------
+| cow      | dog      |
+| cat      | mouse    |
+| horse    | parrot   |
+
+
+Starts a piece of text displayed in a typewriter font.
+
+Starts a piece of text displayed in a typewriter font.
+
+
+
+* List item 1.
+* List item 2.
+* List item 3.
+
+
+*Starts a piece of text displayed in an italic font.*
+
+
+<u>underlined \b bold text - doxy commands are ignored inside 'htmlonly' section </u>""")
+
+
+comment_verifier.check(inspect.getdoc(doxygen_translate.htmlTableFunction),
+r"""The meaning of flags:
+
+:type byFlags: int
+:param byFlags: bits marking required items:
+
+      | Size in bits| Items Required |
+      --------------------------------
+      | 1 - 8       |      1         |
+      | 9 - 16      |      2         |
+      | 17 - 32     |      4         |
+
+      Almost all combinations of above flags are supported by
+      ``htmlTable...`` functions.""")
+
+
+comment_verifier.check(inspect.getdoc(doxygen_translate.htmlEntitiesFunction),
+r"""All entities are treated as commands (C)  TM (R)
+should work also<in text
+>
+&
+'
+"
+`
+'
+"
+"
+-
+--
+
+x
+-
+.
+~
+<=
+>=
+<--
+-->
+Not an  html entity - ignored by Doxygen.
+Not an &text html entity - ampersand is replaced with entity.""")