jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Implemented most of non-ignored doxygen commands translating for java, fixed testcase. The output is not really nice right now, but almost all the commands mentioned in the project plan work ok

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2012-doxygen@13327 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dmitry Kabak 2012-07-16 19:42:30 +00:00
commit db9659c286
5 changed files with 203 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/Devel/plan-gsoc-2012.txt
View file

@ -92,7 +92,7 @@ Functionality
\category - ignored, used only in Objective C
\cite - translated to <i></i> in JD, single quotes in PD
\class - ignored (structural command)
\code - translated to <code></code> in JD, ignored in PD
\code - translated to {@code ...} in JD, ignored in PD
\cond - translated to 'Conditional comment: <condition>'. Later
SWIG may support definitions of conditions in config file.
\copybrief - ignored. Later SWIG may support this command by
@ -172,7 +172,7 @@ Functionality
\namespace - included in package-info.java if nspace feature is enabled,
otherwise ignored, ignored in PD
\nosubgrouping - ignored
\note - ignored in JD, translated to 'Note:' in PD
\note - translated to 'Note:' in both JD and PD
\overload - prints 'This is an overloaded member function, provided for
convenience. It differs from the above function only in what
argument(s) it accepts.' to the output in both JD and PD

2
Examples/test-suite/common.mk
View file

@ -188,7 +188,7 @@ CPP_TEST_CASES += \
director_wombat \
disown \
doxygen_parsing \
doxygen_basic_translate \
doxygen_translate \
dynamic_cast \
empty \
enum_rename \

7
Examples/test-suite/doxygen_translate.i
View file

@ -54,7 +54,7 @@
* This is printed if not
* \endif
*
* \image html testImage.bmp
* \image html testImage.bmp "Hello, world!" asd=10qwe
*
* <ul>
*
@ -68,6 +68,9 @@
*
* \n \n \n
*
* \note Here
* is the note!
*
* \overload
*
* \p someword
@ -122,4 +125,4 @@ int function(int a, float b)
{
}
%}
%}

229
Source/DoxygenTranslator/src/JavaDocConverter.cpp
View file

@ -17,54 +17,82 @@
//TODO {@link} {@linkplain} {@docRoot}, and other useful doxy commands that are not a javadoc tag
// define static tables, they are filled in JavaDocConverter's constructor
std::map<std::string, std::string> JavaDocConverter::escapeTable;
std::map<std::string, JavaDocConverter::tagHandler> JavaDocConverter::tagHandlers;
std::map<std::string, std::pair<JavaDocConverter::tagHandler, std::string > > JavaDocConverter::tagHandlers;
void JavaDocConverter::fillStaticTables() {
if (escapeTable.size()) // fill only once
return;
escapeTable["&"] = "&amp";
escapeTable["\'"] = "&apos";
escapeTable["\""] = "&quot";
escapeTable["<"] = "&lt";
escapeTable[">"] = "&gt";
if (tagHandlers.size()) // fill only once
// these commands insert HTML tags
tagHandlers["c"] = &handleTagC;
tagHandlers["b"] = &handleTagB;
// these commands insert just a single char, some of them need to be escaped
tagHandlers["$"] = &handleTagChar;
tagHandlers["@"] = &handleTagChar;
tagHandlers["\\"] = &handleTagChar;
tagHandlers["<"] = &handleTagChar;
tagHandlers[">"] = &handleTagChar;
tagHandlers["&"] = &handleTagChar;
tagHandlers["#"] = &handleTagChar;
tagHandlers["%"] = &handleTagChar;
tagHandlers["~"] = &handleTagChar;
tagHandlers["\""] = &handleTagChar;
tagHandlers["."] = &handleTagChar;
tagHandlers["::"] = &handleTagChar;
// these commands are stripped out
tagHandlers["brief"] = &handleParagraph;
tagHandlers["details"] = &handleParagraph;
tagHandlers["partofdescription"] = &handleParagraph;
// these commands are kept as-is, they are supported by JavaDoc
tagHandlers["sa"] = &handleTagSeeAll;
tagHandlers["see"] = &handleTagSame;
tagHandlers["param"] = &handleTagSame;
tagHandlers["return"] = &handleTagSame;
tagHandlers["throws"] = &handleTagSame;
tagHandlers["throw"] = &handleTagThrow;
tagHandlers["author"] = &handleTagSame;
tagHandlers["since"] = &handleTagSame;
tagHandlers["version"] = &handleTagSame;
tagHandlers["exception"] = &handleTagSame;
tagHandlers["deprecated"] = &handleTagSame;
// this command just prints it's contents
// (it is internal command of swig's parser, contains plain text)
tagHandlers["plainstd::string"] = &handlePlainString;
tagHandlers["a"] = make_pair(&JavaDocConverter::handleTagHtml, "i");
tagHandlers["arg"] = make_pair(&JavaDocConverter::handleTagHtml, "li");
tagHandlers["b"] = make_pair(&JavaDocConverter::handleTagHtml, "b");
tagHandlers["c"] = make_pair(&JavaDocConverter::handleTagHtml, "code");
tagHandlers["cite"] = make_pair(&JavaDocConverter::handleTagHtml, "i");
tagHandlers["e"] = make_pair(&JavaDocConverter::handleTagHtml, "i");
tagHandlers["li"] = make_pair(&JavaDocConverter::handleTagHtml, "li");
tagHandlers["p"] = make_pair(&JavaDocConverter::handleTagHtml, "code");
// these commands insert just a single char, some of them need to be escaped
tagHandlers["$"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["@"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["\\"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["<"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers[">"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["&"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["#"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["%"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["~"] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["\""] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["."] = make_pair(&JavaDocConverter::handleTagChar, "");
tagHandlers["::"] = make_pair(&JavaDocConverter::handleTagChar, "");
// these commands are stripped out
tagHandlers["attention"] = make_pair(&JavaDocConverter::handleParagraph, "");
tagHandlers["brief"] = make_pair(&JavaDocConverter::handleParagraph, "");
tagHandlers["date"] = make_pair(&JavaDocConverter::handleParagraph, "");
tagHandlers["details"] = make_pair(&JavaDocConverter::handleParagraph, "");
tagHandlers["partofdescription"] = make_pair(&JavaDocConverter::handleParagraph, "");
// these commands are kept as-is, they are supported by JavaDoc
tagHandlers["author"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["authors"] = make_pair(&JavaDocConverter::handleTagSame, "author");
tagHandlers["deprecated"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["exception"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["package"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["param"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["tparam"] = make_pair(&JavaDocConverter::handleTagSame, "param");
tagHandlers["result"] = make_pair(&JavaDocConverter::handleTagSame, "return");
tagHandlers["return"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["returns"] = make_pair(&JavaDocConverter::handleTagSame, "return");
tagHandlers["see"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["sa"] = make_pair(&JavaDocConverter::handleTagSame, "see");
tagHandlers["since"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["throws"] = make_pair(&JavaDocConverter::handleTagSame, "");
tagHandlers["throw"] = make_pair(&JavaDocConverter::handleTagSame, "throws");
tagHandlers["version"] = make_pair(&JavaDocConverter::handleTagSame, "");
// these commands have special handlers
tagHandlers["code"] = make_pair(&JavaDocConverter::handleTagExtended, "code");
tagHandlers["cond"] = make_pair(&JavaDocConverter::handleTagMessage, "Conditional comment: ");
tagHandlers["copyright"] = make_pair(&JavaDocConverter::handleTagMessage, "Copyright: ");
tagHandlers["else"] = make_pair(&JavaDocConverter::handleTagIf, "Else: ");
tagHandlers["elseif"] = make_pair(&JavaDocConverter::handleTagIf, "Else if: ");
tagHandlers["endcond"] = make_pair(&JavaDocConverter::handleTagMessage, "End of conditional comment.");
tagHandlers["if"] = make_pair(&JavaDocConverter::handleTagIf, "If: ");
tagHandlers["ifnot"] = make_pair(&JavaDocConverter::handleTagIf, "If not: ");
tagHandlers["image"] = make_pair(&JavaDocConverter::handleTagImage, "");
tagHandlers["link"] = make_pair(&JavaDocConverter::handleTagExtended, "link");
tagHandlers["note"] = make_pair(&JavaDocConverter::handleTagMessage, "Note: ");
tagHandlers["overload"] = make_pair(&JavaDocConverter::handleTagMessage, "This is an overloaded member function, provided for"
" convenience. It differs from the above function only in what"
" argument(s) it accepts.");
tagHandlers["par"] = make_pair(&JavaDocConverter::handleTagPar, "");
tagHandlers["remark"] = make_pair(&JavaDocConverter::handleTagMessage, "Remarks: ");
tagHandlers["remarks"] = make_pair(&JavaDocConverter::handleTagMessage, "Remarks: ");
tagHandlers["todo"] = make_pair(&JavaDocConverter::handleTagMessage, "TODO: ");
tagHandlers["verbatim"] = make_pair(&JavaDocConverter::handleTagExtended, "literal");
tagHandlers["warning"] = make_pair(&JavaDocConverter::handleTagMessage, "Warning: ");
// this command just prints it's contents
// (it is internal command of swig's parser, contains plain text)
tagHandlers["plainstd::string"] = make_pair(&JavaDocConverter::handlePlainString, "");
tagHandlers["plainstd::endl"] = make_pair(&JavaDocConverter::handleNewLine, "");
tagHandlers["n"] = make_pair(&JavaDocConverter::handleNewLine, "");
}
@ -73,7 +101,7 @@ JavaDocConverter::JavaDocConverter() : debug(false) {
}
std::string JavaDocConverter::formatCommand(std::string unformattedLine, int indent) {
std::string formattedLines = "\n * ";
std::string formattedLines;
int lastPosition = 0;
int i = 0;
int isFirstLine = 1;
@ -89,11 +117,11 @@ std::string JavaDocConverter::formatCommand(std::string unformattedLine, int ind
if (i > 0 && i + 1 < (int) unformattedLine.length()) {
if (!isFirstLine)
for (int j = 0; j < indent; j++) {
formattedLines.append("\t");
} else {
isFirstLine = 0;
}
for (int j = 0; j < indent; j++) {
formattedLines.append("\t");
} else {
isFirstLine = 0;
}
formattedLines.append(unformattedLine.substr(lastPosition, i - lastPosition + 1));
formattedLines.append("\n *");
@ -102,7 +130,7 @@ std::string JavaDocConverter::formatCommand(std::string unformattedLine, int ind
if (lastPosition < (int) unformattedLine.length()) {
if (!isFirstLine) {
for (int j = 0; j < indent; j++) {
formattedLines.append("\t");
formattedLines.append("\t");
}
}
formattedLines.append(unformattedLine.substr(lastPosition, unformattedLine.length() - lastPosition));
@ -129,45 +157,96 @@ std::string JavaDocConverter::translateSubtree(DoxygenEntity & doxygenEntity) {
void JavaDocConverter::translateEntity(DoxygenEntity& tag, std::string& translatedComment) {
// check if we have needed handler and call it
std::map<std::string, tagHandler>::iterator it;
it = tagHandlers.find(tag.typeOfEntity);
std::map<std::string, std::pair<tagHandler, std::string > >::iterator it;
it = tagHandlers.find(tag.typeOfEntity);
if (it!=tagHandlers.end())
(*it).second(this, tag, translatedComment);
(this->*(it->second.first))(tag, translatedComment, it->second.second);
}
void JavaDocConverter::handleTagC(JavaDocConverter* converter, DoxygenEntity& tag, std::string& translatedComment) {
translatedComment += "<tt>" + tag.data + "</tt> ";
void JavaDocConverter::handleTagHtml(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
if (tag.entityList.size()) // do not include empty tags
translatedComment += "<" + arg + ">" + translateSubtree(tag) + "</" + arg + ">";
}
void JavaDocConverter::handleTagB(JavaDocConverter* converter, DoxygenEntity& tag, std::string& translatedComment) {
translatedComment += "<b>" + tag.data + "</b> ";
void JavaDocConverter::handleNewLine(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
translatedComment += "\n * ";
}
void JavaDocConverter::handleTagThrow(JavaDocConverter* converter, DoxygenEntity& tag, std::string& translatedComment) {
tag.typeOfEntity = "throws";
handleTagSame(converter, tag, translatedComment);
}
void JavaDocConverter::handleTagSeeAll(JavaDocConverter* converter, DoxygenEntity& tag, std::string& translatedComment) {
tag.typeOfEntity = "see";
handleTagSame(converter, tag, translatedComment);
}
void JavaDocConverter::handleTagChar(JavaDocConverter* converter, DoxygenEntity& tag, std::string& translatedComment) {
// escape it if we can, else just print
if (escapeTable.find(tag.typeOfEntity)!=escapeTable.end())
translatedComment += escapeTable[tag.typeOfEntity];
void JavaDocConverter::handleTagChar(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
// escape it if we need to, else just print
if (arg.size())
translatedComment += arg;
else
translatedComment += tag.typeOfEntity;
translatedComment += " ";
}
void JavaDocConverter::handleTagSame(JavaDocConverter* converter, DoxygenEntity& tag, std::string& translatedComment) {
translatedComment += converter->formatCommand(std::string("@" + tag.typeOfEntity + "\t" + converter->translateSubtree(tag)), 2);
void JavaDocConverter::handleTagSame(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
if (arg.size())
tag.typeOfEntity = arg;
translatedComment += formatCommand(std::string("@" + tag.typeOfEntity + " " + translateSubtree(tag)), 2);
}
void JavaDocConverter::handleParagraph(JavaDocConverter* converter, DoxygenEntity& tag, std::string& translatedComment) {
translatedComment += converter->formatCommand(converter->translateSubtree(tag), 0);
void JavaDocConverter::handleParagraph(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
translatedComment += formatCommand(translateSubtree(tag), 0);
}
void JavaDocConverter::handlePlainString(JavaDocConverter* converter, DoxygenEntity& tag, std::string& translatedComment) {
void JavaDocConverter::handlePlainString(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
translatedComment += tag.data;
if (tag.data.size() && tag.data[tag.data.size()-1] != ' ')
translatedComment += " ";
}
void JavaDocConverter::handleTagExtended(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
std::string dummy;
translatedComment += "{@" + arg + " ";
handleParagraph(tag, translatedComment, dummy);
translatedComment += "}";
}
void JavaDocConverter::handleTagIf(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
std::string dummy;
translatedComment += arg;
if (tag.entityList.size()) {
translatedComment += tag.entityList.begin()->data;
//handleNewLine(tag, translatedComment, dummy);
tag.entityList.pop_front();
translatedComment += " {" + translateSubtree(tag) + "}";
}
}
void JavaDocConverter::handleTagMessage(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
std::string dummy;
translatedComment += formatCommand(arg, 0);
handleParagraph(tag, translatedComment, dummy);
}
void JavaDocConverter::handleTagImage(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
if (tag.entityList.size() < 2)
return;
std::string file;
std::string title;
std::list <DoxygenEntity>::iterator it = tag.entityList.begin();
if (it->data != "html")
return;
it++;
file = it->data;
it++;
if (it != tag.entityList.end())
title = it->data;
translatedComment += "<img src=" + file;
if (title.size())
translatedComment += " alt=\"" + title +"\"";
translatedComment += " />";
}
void JavaDocConverter::handleTagPar(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
std::string dummy;
translatedComment += "<p";
if (tag.entityList.size())
translatedComment += " alt=\"" + tag.entityList.begin()->data + "\"";
translatedComment += ">";
tag.entityList.pop_front();
handleParagraph(tag, translatedComment, dummy);
translatedComment += "</p>";
}
String *JavaDocConverter::makeDocumentation(Node *node) {
String *documentation = getDoxygenComment(node);

54
Source/DoxygenTranslator/src/JavaDocConverter.h
View file

@ -27,42 +27,70 @@ public:
protected:
std::string formatCommand(std::string unformattedLine, int indent);
std::string javaDocFormat(DoxygenEntity & doxygenEntity);
std::string translateSubtree(DoxygenEntity & doxygenEntity);
void translateEntity(DoxygenEntity &tag, std::string &translatedComment);
/*
* Typedef for the function that handles one tag
* arg - some string argument to easily pass it through lookup table
*/
typedef void (*tagHandler)(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
typedef void (JavaDocConverter::*tagHandler)(DoxygenEntity &tag,
std::string &translatedComment, std::string &arg);
/*
* Here comes various tag handlers
* Wrap the command data with the html tag
* arg - html tag, with no braces
*/
static void handleTagC(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
static void handleTagB(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
static void handleTagThrow(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
static void handleTagSeeAll(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
void handleTagHtml(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Just prints new line
*/
void handleNewLine(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Print the name of tag to the output, used for escape-commands
* arg - html-escaped variant, if not provided the command data is used
*/
static void handleTagChar(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
void handleTagChar(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Do not translate and print as-is
* arg - the new tag name, if it needs to be renamed
*/
static void handleTagSame(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
void handleTagSame(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Print only the content and strip original tag
*/
static void handleParagraph(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
void handleParagraph(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Print only data part of code
*/
static void handlePlainString(JavaDocConverter *converter, DoxygenEntity &tag, std::string &translatedComment);
void handlePlainString(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Print extended Javadoc command, like {@code ...} or {@literal ...}
* arg - command name
*/
void handleTagExtended(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Print the if-elseif-else-endif section
*/
void handleTagIf(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Prints the specified message, than the contents of the tag
* arg - message
*/
void handleTagMessage(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Insert <img src=... /> tag if the 'format' field is specified as 'html'
*/
void handleTagImage(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
/*
* Insert <p alt='title'>...</p>
*/
void handleTagPar(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
private:
bool debug;
static std::map<std::string, tagHandler> tagHandlers;
static std::map<std::string, std::string> escapeTable;
// this contains the handler pointer and one string argument
static std::map<std::string, std::pair<tagHandler, std::string> > tagHandlers;
void fillStaticTables();
};