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 "<" in HTML documentation Fix broken link to java.sun.com in Doxygen documentation Fix using com.sun.tools.javadoc package under macOS Fix error reporting for special characters in Doxygen parsing code Switch Python Doxygen unit tests to use inspect.getdoc() Use correct separator in Java class path under Windows. Remove executable permission from appveyor.yml. Use JAVA_HOME value in configure to detect Java. Display JAVA_HOME value in "make java_version". Fix harmless MSVC warning in DoxygenTranslator code. Reset "_last" for all but first enum elements. Don't duplicate Javadoc from global enum Doxygen comments twice. Move Doxygen comments concatenation from the parser to the lexer. Fix shift/reduce conflicts in Doxygen pre/post comment parsing. Rewrote part of the grammar dealing with Doxygen comments for enums. No changes, just remove spurious white space only differences. Move Doxygen comment mangling from the parser to the lexer. Merge "-builtin" autodoc bugs workarounds from master into test. Quote JAVA_HOME variable value in Java test suite makefile. Remove unused C_COMMENT_STRING terminal from the grammar. Fix missing returns in the Doxygen test suite code. Fix trimming whitespace from Doxygen comments. Remove code not doing anything from PyDocConverter. Remove unused <sstream> header. Remove unreferenced struct declaration. Remove unused Swig_warn() function. Remove any whitespace before ignored Doxygen commands. Remove trailing space from one of Doxygen tests. Fix autodoc strings generated in Python builtin case and the test. Fix Doxygen unit test in Python "-builtin" case. Use class docstrings in "-builtin" Python case. Don't indent Doxygen doc strings in generated Python code. Add a possibility to flexibly ignore custom Doxygen tags. Stop completely ignoring many Doxygen comments. Fix structural Doxygen comment recognition in the parser. No changes, just make checking for Doxygen structural tags more sane. Use "//", not "#", for comments in SWIG input. Allow upper case letters and digits in Doxygen words. Pass the node the Doxygen comment is attached to to DoxygenParser. Get rid of findCommand() which duplicaed commandBelongs(). Recognize unknown Doxygen tags correctly. No real changes, just pass original command to commandBelongs(). Describe Doxygen-specific %features in a single place. Give warnings for unknown Doxygen commands in Doxygen parser. Document the return type when translating Doxygen @return to Python. Fix translated Doxygen comments for overloaded functions in Python. Also merge Doxygen comments for overloaded constructors in Python. Allow using enum elements as default values for Python functions. Don't always use "*args" for all Python wrapper functions. No real changes, just make PYTHON::check_kwargs() const. Refactor: move makeParameterName() to common Language base class. Remove long line wrapping from Python parameter list generation code. Simplify and make more efficient building Python docstrings. Translate Doxygen code blocks to Sphinx code blocks. Add a simple test of multiple parameters to Doxygen test suite. Make Python parameters types hyperlinks in the doc strings. Make Language::classLookup() and enumLookup() static. Fix arguments of @param, @return etc translations to Python. Remove unused method from PyDocConverter. No real changes, just remove an unnecessary variable. Preserve relative indentation when parsing Doxygen comments. Use Sphinx-friendly formatting for overloaded functions documentation. Add poor man trailing white space detection to Doxygen Python tests. ...
This commit is contained in:
William S Fulton
commit
33921666a1
123 changed files with 12964 additions and 1344 deletions
|
|
@ -4,6 +4,7 @@ class
|
|||
constants
|
||||
contract
|
||||
docstrings
|
||||
doxygen
|
||||
enum
|
||||
exception
|
||||
exceptproxy
|
||||
|
|
|
|||
27
Examples/python/doxygen/Makefile
Normal file
27
Examples/python/doxygen/Makefile
Normal file
|
|
@ -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
|
||||
48
Examples/python/doxygen/example.cxx
Normal file
48
Examples/python/doxygen/example.cxx
Normal file
|
|
@ -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);
|
||||
}
|
||||
|
||||
152
Examples/python/doxygen/example.dsp
Normal file
152
Examples/python/doxygen/example.dsp
Normal file
|
|
@ -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
|
||||
107
Examples/python/doxygen/example.h
Normal file
107
Examples/python/doxygen/example.h
Normal file
|
|
@ -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;
|
||||
|
||||
17
Examples/python/doxygen/example.i
Normal file
17
Examples/python/doxygen/example.i
Normal file
|
|
@ -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>;
|
||||
|
||||
28
Examples/python/doxygen/runme.py
Normal file
28
Examples/python/doxygen/runme.py
Normal file
|
|
@ -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"
|
||||
Loading…
Add table
Add a link
Reference in a new issue