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
|
|
@ -15,6 +15,7 @@
|
|||
#include <limits.h> // for INT_MAX
|
||||
#include "cparse.h"
|
||||
#include <ctype.h>
|
||||
#include "javadoc.h"
|
||||
|
||||
/* Hash type used for upcalls from C/C++ */
|
||||
typedef DOH UpcallData;
|
||||
|
|
@ -46,7 +47,9 @@ class JAVA:public Language {
|
|||
bool global_variable_flag; // Flag for when wrapping a global variable
|
||||
bool old_variable_names; // Flag for old style variable names in the intermediary class
|
||||
bool member_func_flag; // flag set when wrapping a member function
|
||||
|
||||
bool doxygen; //flag for converting found doxygen to javadoc
|
||||
bool comment_creation_chatter; //flag for getting information about where comments were created in java.cxx
|
||||
|
||||
String *imclass_name; // intermediary class name
|
||||
String *module_class_name; // module class name
|
||||
String *constants_interface_name; // constants interface name
|
||||
|
|
@ -120,6 +123,8 @@ public:
|
|||
global_variable_flag(false),
|
||||
old_variable_names(false),
|
||||
member_func_flag(false),
|
||||
doxygen(false),
|
||||
comment_creation_chatter(false),
|
||||
imclass_name(NULL),
|
||||
module_class_name(NULL),
|
||||
constants_interface_name(NULL),
|
||||
|
|
@ -164,6 +169,10 @@ public:
|
|||
director_multiple_inheritance = 0;
|
||||
director_language = 1;
|
||||
}
|
||||
|
||||
~JAVA() {
|
||||
delete doxygenTranslator;
|
||||
}
|
||||
|
||||
/* -----------------------------------------------------------------------------
|
||||
* constructIntermediateClassName()
|
||||
|
|
@ -256,6 +265,8 @@ public:
|
|||
|
||||
SWIG_library_directory("java");
|
||||
|
||||
int doxygen_translator_flags = 0;
|
||||
|
||||
// Look for certain command line options
|
||||
for (int i = 1; i < argc; i++) {
|
||||
if (argv[i]) {
|
||||
|
|
@ -277,6 +288,16 @@ public:
|
|||
Printf(stderr, "Deprecated command line option: %s. Proxy classes are now generated by default.\n", argv[i]);
|
||||
Swig_mark_arg(i);
|
||||
proxy_flag = true;
|
||||
} else if ((strcmp(argv[i], "-doxygen") == 0)) {
|
||||
Swig_mark_arg(i);
|
||||
doxygen = true;
|
||||
scan_doxygen_comments = true;
|
||||
} else if ((strcmp(argv[i], "-debug-doxygen-translator") == 0)) {
|
||||
Swig_mark_arg(i);
|
||||
doxygen_translator_flags |= DoxygenTranslator::debug_translator;
|
||||
} else if ((strcmp(argv[i], "-debug-doxygen-parser") == 0)) {
|
||||
Swig_mark_arg(i);
|
||||
doxygen_translator_flags |= DoxygenTranslator::debug_parser;
|
||||
} else if ((strcmp(argv[i], "-noproxy") == 0)) {
|
||||
Swig_mark_arg(i);
|
||||
proxy_flag = false;
|
||||
|
|
@ -300,6 +321,9 @@ public:
|
|||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (doxygen)
|
||||
doxygenTranslator = new JavaDocConverter(doxygen_translator_flags);
|
||||
|
||||
// Add a symbol to the parser for conditional compilation
|
||||
Preprocessor_define("SWIGJAVA 1", 0);
|
||||
|
|
@ -567,6 +591,13 @@ public:
|
|||
if (module_imports)
|
||||
Printf(f_module, "%s\n", module_imports);
|
||||
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter)
|
||||
Printf(f_module, "/* This was generated from top() */");
|
||||
Printv(f_module, Char(doxygen_comments), NIL);
|
||||
Delete(doxygen_comments);
|
||||
}
|
||||
if (Len(module_class_modifiers) > 0)
|
||||
Printf(f_module, "%s ", module_class_modifiers);
|
||||
Printf(f_module, "%s ", module_class_name);
|
||||
|
|
@ -1243,6 +1274,15 @@ public:
|
|||
EnumFeature enum_feature = decodeEnumFeature(n);
|
||||
String *typemap_lookup_type = Getattr(n, "name");
|
||||
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter) {
|
||||
Printf(enum_code, "/* This was generated from enumDeclaration() */");
|
||||
}
|
||||
Printv(enum_code, Char(doxygen_comments), NIL);
|
||||
Delete(doxygen_comments);
|
||||
}
|
||||
|
||||
if ((enum_feature != SimpleEnum) && symname && typemap_lookup_type) {
|
||||
// Wrap (non-anonymous) C/C++ enum within a typesafe, typeunsafe or proper Java enum
|
||||
|
||||
|
|
@ -1265,8 +1305,16 @@ public:
|
|||
Replaceall(enum_code, "$static ", "");
|
||||
Delete(scope);
|
||||
} else {
|
||||
// Wrap C++ enum with integers - just indicate start of enum with a comment, no comment for anonymous enums of any sort
|
||||
if (symname && !Getattr(n, "unnamedinstance"))
|
||||
// Translate and write javadoc comment for the enum itself if flagged
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter)
|
||||
Printf(constants_code, "/* This was generated from enumDeclaration() */");
|
||||
Printf(constants_code, "/* Comment for enum %s */\n", Getattr(n, "unnamedinstance") ? "" : symname);
|
||||
Printf(constants_code, Char(doxygen_comments));
|
||||
Printf(constants_code, "\n");
|
||||
Delete(doxygen_comments);
|
||||
} else if (symname && !Getattr(n, "unnamedinstance"))
|
||||
Printf(constants_code, " // %s \n", symname);
|
||||
}
|
||||
|
||||
|
|
@ -1418,12 +1466,24 @@ public:
|
|||
}
|
||||
if (!addSymbol(symname, n, scope))
|
||||
return SWIG_ERROR;
|
||||
|
||||
if ((enum_feature == ProperEnum) && parent_name && !unnamedinstance) {
|
||||
if (!GetFlag(n, "firstenumitem"))
|
||||
Printf(enum_code, ",\n");
|
||||
}
|
||||
|
||||
// Translate and write javadoc comment if flagged
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter)
|
||||
Printf(enum_code, "/* This was generated from enumvalueDeclaration() */");
|
||||
Printv(enum_code, Char(doxygen_comments), NIL);
|
||||
Delete(doxygen_comments);
|
||||
}
|
||||
|
||||
if ((enum_feature == ProperEnum) && parent_name && !unnamedinstance) {
|
||||
// Wrap (non-anonymous) C/C++ enum with a proper Java enum
|
||||
// Emit the enum item.
|
||||
if (!GetFlag(n, "firstenumitem"))
|
||||
Printf(enum_code, ",\n");
|
||||
Printf(enum_code, " %s", symname);
|
||||
if (Getattr(n, "enumvalue")) {
|
||||
String *value = enumValue(n);
|
||||
|
|
@ -1497,6 +1557,15 @@ public:
|
|||
String *constants_code = NewString("");
|
||||
Swig_save("constantWrapper", n, "value", NIL);
|
||||
|
||||
// Translate and write javadoc comment if flagged
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter)
|
||||
Printf(constants_code, "/* This was generated from constantWrapper() */");
|
||||
Printv(constants_code, Char(doxygen_comments), NIL);
|
||||
Delete(doxygen_comments);
|
||||
}
|
||||
|
||||
bool is_enum_item = (Cmp(nodeType(n), "enumitem") == 0);
|
||||
|
||||
const String *itemname = (proxy_flag && wrapping_member_flag) ? variable_name : symname;
|
||||
|
|
@ -1936,6 +2005,16 @@ public:
|
|||
|
||||
// Pure Java interfaces
|
||||
const String *pure_interfaces = typemapLookup(n, "javainterfaces", typemap_lookup_type, WARN_NONE);
|
||||
|
||||
// Translate and write javadoc comment if flagged
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter)
|
||||
Printf(proxy_class_def, "/* This was generated from emitProxyClassDefAndCPPCasts() */");
|
||||
Printv(proxy_class_def, Char(doxygen_comments), NIL);
|
||||
Delete(doxygen_comments);
|
||||
}
|
||||
|
||||
if (*Char(interface_list) && *Char(pure_interfaces))
|
||||
Append(interface_list, ", ");
|
||||
Append(interface_list, pure_interfaces);
|
||||
|
|
@ -2424,6 +2503,15 @@ public:
|
|||
setter_flag = (Cmp(Getattr(n, "sym:name"), Swig_name_set(getNSpace(), Swig_name_member(0, getClassPrefix(), variable_name))) == 0);
|
||||
}
|
||||
|
||||
// Translate and write javadoc comment if flagged
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter)
|
||||
Printf(function_code, "/* This was generated from proxyclassfunctionhandler() */");
|
||||
Printv(function_code, Char(doxygen_comments), NIL);
|
||||
Delete(doxygen_comments);
|
||||
}
|
||||
|
||||
/* Start generating the proxy function */
|
||||
const String *methodmods = Getattr(n, "feature:java:methodmodifiers");
|
||||
methodmods = methodmods ? methodmods : (is_public(n) ? public_string : protected_string);
|
||||
|
|
@ -2614,7 +2702,7 @@ public:
|
|||
Printf(interface_class_code, ";\n");
|
||||
}
|
||||
generateThrowsClause(n, function_code);
|
||||
Printf(function_code, " %s\n\n", tm ? (const String *) tm : empty_string);
|
||||
Printf(function_code, " %s\n\n", tm ? tm : empty_string);
|
||||
Printv(proxy_class_code, function_code, NIL);
|
||||
|
||||
Delete(pre_code);
|
||||
|
|
@ -2659,6 +2747,15 @@ public:
|
|||
tm = Getattr(n, "tmap:jtype"); // typemaps were attached earlier to the node
|
||||
Printf(im_return_type, "%s", tm);
|
||||
|
||||
// Translate and write javadoc comment if flagged
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter)
|
||||
Printf(function_code, "/* This was generated from constructionhandler() */");
|
||||
Printv(function_code, Char(doxygen_comments), NIL);
|
||||
Delete(doxygen_comments);
|
||||
}
|
||||
|
||||
Printf(function_code, " %s %s(", methodmods, proxy_class_name);
|
||||
Printf(helper_code, " static private %s SwigConstruct%s(", im_return_type, proxy_class_name);
|
||||
|
||||
|
|
@ -2924,6 +3021,15 @@ public:
|
|||
String *pre_code = NewString("");
|
||||
String *post_code = NewString("");
|
||||
|
||||
// Translate and write javadoc comment if flagged
|
||||
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
|
||||
String *doxygen_comments = doxygenTranslator->getDocumentation(n);
|
||||
if (comment_creation_chatter)
|
||||
Printf(function_code, "/* This was generated from moduleClassFunctionHandler() */");
|
||||
Printv(function_code, doxygen_comments, NIL);
|
||||
Delete(doxygen_comments);
|
||||
}
|
||||
|
||||
if (l) {
|
||||
if (SwigType_type(Getattr(l, "type")) == T_VOID) {
|
||||
l = nextSibling(l);
|
||||
|
|
@ -3076,7 +3182,7 @@ public:
|
|||
}
|
||||
|
||||
generateThrowsClause(n, function_code);
|
||||
Printf(function_code, " %s\n\n", tm ? (const String *) tm : empty_string);
|
||||
Printf(function_code, " %s\n\n", tm ? tm : empty_string);
|
||||
Printv(module_class_code, function_code, NIL);
|
||||
|
||||
Delete(pre_code);
|
||||
|
|
@ -4873,6 +4979,9 @@ extern "C" Language *swig_java(void) {
|
|||
|
||||
const char *JAVA::usage = "\
|
||||
Java Options (available with -java)\n\
|
||||
-doxygen - Convert C++ doxygen comments to JavaDoc comments in proxy classes\n\
|
||||
-debug-doxygen-parser - Display doxygen parser module debugging information\n\
|
||||
-debug-doxygen-translator - Display doxygen translator module debugging information\n\
|
||||
-nopgcpp - Suppress premature garbage collection prevention parameter\n\
|
||||
-noproxy - Generate the low-level functional interface instead\n\
|
||||
of proxy classes\n\
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue