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

Doxygen warnings cleanup

Browse source 
- Remove unused warnings.
- Refactor some warnings.
- Document all Doxygen warnings.
This commit is contained in:
William S Fulton 2018-06-05 18:40:30 +01:00
commit 396910c100
4 changed files with 40 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

12
Doc/Manual/Warnings.html
View file

@ -506,7 +506,7 @@ example.i(4) : Syntax error in input(1).
<H3><a name="Warnings_nn14">17.9.5 Code generation (500-599)</a></H3> <H3><a name="Warnings_nn14">17.9.5 Code generation (500-559)</a></H3>
<ul> <ul>
@ -535,6 +535,16 @@ example.i(4) : Syntax error in input(1).
<li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'. <li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'.
</ul> </ul>
<H3><a name="Warnings_doxygen">Doxygen comments (560-599)</a></H3>
<ul>
<li>560: Unknown Doxygen command: <em>command</em>.</li>
<li>561: Unexpected end of Doxygen comment encountered.</li>
<li>562: Expected Doxygen command: <em>command</em></li>
<li>563: Doxygen HTML error for tag <em>tag</em>: <em>error text</em>.</li>
<li>564: Error parsing Doxygen command <em>command</em>: <em>error text</em>. Command ignored."</li>
</ul>
<H3><a name="Warnings_nn15">17.9.6 Language module specific (700-899) </a></H3> <H3><a name="Warnings_nn15">17.9.6 Language module specific (700-899) </a></H3>

2
Examples/test-suite/errors/doxygen_unknown_command.stderr
View file

@ -1 +1 @@
doxygen_unknown_command.i:4: Warning 560: Doxygen parser warning: unknown command "unknown". doxygen_unknown_command.i:4: Warning 560: Unknown Doxygen command: unknown.

53
Source/Doxygen/doxyparser.cxx
View file

@ -279,7 +279,7 @@ std::string DoxygenParser::getStringTilEndCommand(const std::string &theCommand,
m_tokenListIt++; m_tokenListIt++;
} }
printListError(WARN_DOXYGEN_COMMAND_EXPECTED, theCommand + " command expected"); printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected Doxygen command: " + theCommand + ".");
return description; return description;
} }
@ -384,7 +384,7 @@ void DoxygenParser::addCommandWord(const std::string &theCommand, const TokenLis
aNewList.push_back(DoxygenEntity("plainstd::string", name)); aNewList.push_back(DoxygenEntity("plainstd::string", name));
doxyList.push_back(DoxygenEntity(theCommand, aNewList)); doxyList.push_back(DoxygenEntity(theCommand, aNewList));
} else { } else {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No word followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored.");
} }
} }
@ -412,7 +412,7 @@ void DoxygenParser::addCommandEndCommand(const std::string &theCommand, const To
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
TokenListCIt endCommand = getEndCommand("end" + theCommand, tokList); TokenListCIt endCommand = getEndCommand("end" + theCommand, tokList);
if (endCommand == tokList.end()) { if (endCommand == tokList.end()) {
printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected end" + theCommand); printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected Doxygen command: end" + theCommand + ".");
return; return;
} }
DoxygenEntityList aNewList; DoxygenEntityList aNewList;
@ -428,7 +428,7 @@ void DoxygenParser::addCommandWordParagraph(const std::string &theCommand, const
std::string name = getNextWord(); std::string name = getNextWord();
if (name.empty()) { if (name.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No word followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored.");
return; return;
} }
TokenListCIt endOfParagraph = getEndOfParagraph(tokList); TokenListCIt endOfParagraph = getEndOfParagraph(tokList);
@ -443,7 +443,7 @@ void DoxygenParser::addCommandWordLine(const std::string &theCommand, const Toke
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
std::string name = getNextWord(); std::string name = getNextWord();
if (name.empty()) { if (name.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No word followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored.");
return; return;
} }
@ -461,7 +461,7 @@ void DoxygenParser::addCommandWordOWordOWord(const std::string &theCommand, cons
std::string name = getNextWord(); std::string name = getNextWord();
if (name.empty()) { if (name.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No word followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored.");
return; return;
} }
std::string headerfile = getNextWord(); std::string headerfile = getNextWord();
@ -487,8 +487,7 @@ void DoxygenParser::addCommandOWord(const std::string &theCommand, const TokenLi
void DoxygenParser::addCommandErrorThrow(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &) { void DoxygenParser::addCommandErrorThrow(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": Unexpectedly encountered this command.");
"Encountered: " + theCommand + "\nThis command should not have been encountered. Behaviour past this may be unpredictable");
m_tokenListIt = getOneLine(tokList); m_tokenListIt = getOneLine(tokList);
} }
@ -524,17 +523,17 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
std::string key = getNextWord(); std::string key = getNextWord();
if (key.empty()) { if (key.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No key followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No key followed the command. Command ignored.");
return; return;
} }
std::string heading = getNextWord(); std::string heading = getNextWord();
if (key.empty()) { if (key.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No heading followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No heading followed the command. Command ignored.");
return; return;
} }
std::string title = getNextWord(); std::string title = getNextWord();
if (title.empty()) { if (title.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No title followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No title followed the command. Command ignored.");
return; return;
} }
TokenListCIt endOfParagraph = getEndOfParagraph(tokList); TokenListCIt endOfParagraph = getEndOfParagraph(tokList);
@ -592,7 +591,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
std::string name = getNextWord(); std::string name = getNextWord();
if (name.empty()) { if (name.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No word followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored.");
return; return;
} }
DoxygenEntityList aNewList; DoxygenEntityList aNewList;
@ -609,7 +608,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
std::string name = getNextWord(); std::string name = getNextWord();
if (name.empty()) { if (name.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No key followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No key followed the command. Command ignored.");
return; return;
} }
DoxygenEntityList aNewList; DoxygenEntityList aNewList;
@ -638,7 +637,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
std::string name = getNextWord(); std::string name = getNextWord();
if (name.empty()) { if (name.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No name followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No name followed the command. Command ignored.");
return; return;
} }
std::string text = getNextWord(); std::string text = getNextWord();
@ -685,7 +684,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
std::string file = getNextWord(); std::string file = getNextWord();
if (file.empty()) { if (file.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No file followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No file followed the command. Command ignored.");
return; return;
} }
std::string caption = getNextWord(); std::string caption = getNextWord();
@ -700,12 +699,12 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
std::string format = getNextWord(); std::string format = getNextWord();
if (format.empty()) { if (format.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No format followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No format followed the command. Command ignored.");
return; return;
} }
std::string file = getNextWord(); std::string file = getNextWord();
if (file.empty()) { if (file.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No name followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No name followed the command. Command ignored.");
return; return;
} }
std::string caption = getNextWord(); std::string caption = getNextWord();
@ -726,7 +725,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
cout << "Parsing " << theCommand << endl; cout << "Parsing " << theCommand << endl;
std::string name = getNextWord(); std::string name = getNextWord();
if (name.empty()) { if (name.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "There should be at least one word following the '" + theCommand + "' command. Command ignored."); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": There should be at least one word following the command. Command ignored.");
return; return;
} }
DoxygenEntityList aNewList; DoxygenEntityList aNewList;
@ -749,7 +748,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
if (needsCond) { if (needsCond) {
cond = getNextWord(); cond = getNextWord();
if (cond.empty()) { if (cond.empty()) {
printListError(WARN_DOXYGEN_COMMAND_ERROR, "No word followed " + theCommand + " command. Not added"); printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored.");
return; return;
} }
} }
@ -777,7 +776,7 @@ void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenL
} }
if (endCommand == tokList.end()) { if (endCommand == tokList.end()) {
printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "No corresponding endif found"); printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected Doxygen command: endif.");
return; return;
} }
@ -835,7 +834,7 @@ void DoxygenParser::ignoreCommand(const std::string &theCommand, const TokenList
if (!endCommand.empty()) { if (!endCommand.empty()) {
TokenListCIt itEnd = getEndCommand(endCommand, tokList); TokenListCIt itEnd = getEndCommand(endCommand, tokList);
if (itEnd == tokList.end()) { if (itEnd == tokList.end()) {
printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected " + endCommand); printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected Doxygen command: " + endCommand + ".");
return; return;
} }
// If we ignore the command, also ignore any whitespace preceding it as we // If we ignore the command, also ignore any whitespace preceding it as we
@ -979,7 +978,7 @@ DoxygenEntityList DoxygenParser::parse(TokenListCIt endParsingIndex, const Token
if (endParsingIndex != tokList.end() && m_tokenListIt == tokList.end()) { if (endParsingIndex != tokList.end() && m_tokenListIt == tokList.end()) {
// this could happen if we can't reach the original endParsingIndex // this could happen if we can't reach the original endParsingIndex
printListError(WARN_DOXYGEN_UNEXPECTED_END_OF_COMMENT, "Unexpected end of comment encountered"); printListError(WARN_DOXYGEN_UNEXPECTED_END_OF_COMMENT, "Unexpected end of Doxygen comment encountered.");
break; break;
} }
} }
@ -1052,7 +1051,7 @@ bool DoxygenParser::addDoxyCommand(DoxygenParser::TokenList &tokList, const std:
const TokenListCIt itSave = m_tokenListIt; const TokenListCIt itSave = m_tokenListIt;
m_tokenListIt = m_tokenList.end(); m_tokenListIt = m_tokenList.end();
printListError(WARN_DOXYGEN_UNKNOWN_COMMAND, "unknown command \"" + cmd + '"'); printListError(WARN_DOXYGEN_UNKNOWN_COMMAND, "Unknown Doxygen command: " + cmd + ".");
m_tokenListIt = itSave; m_tokenListIt = itSave;
} }
@ -1177,13 +1176,13 @@ void DoxygenParser::processHtmlTags(size_t &pos, const std::string &line) {
// for example <A ...>, <IMG ...>, ... // for example <A ...>, <IMG ...>, ...
if (isEndHtmlTag) { if (isEndHtmlTag) {
m_tokenListIt = m_tokenList.end(); m_tokenListIt = m_tokenList.end();
printListError(WARN_DOXYGEN_COMMAND_ERROR, "Illegal end HTML tag without '>' found! Tag: " + cmd); printListError(WARN_DOXYGEN_HTML_ERROR, "Doxygen HTML error for tag " + cmd + ": Illegal end HTML tag without '>' found.");
} }
endHtmlPos = line.find(">", pos); endHtmlPos = line.find(">", pos);
if (endHtmlPos == string::npos) { if (endHtmlPos == string::npos) {
m_tokenListIt = m_tokenList.end(); m_tokenListIt = m_tokenList.end();
printListError(WARN_DOXYGEN_COMMAND_ERROR, "HTML tag without '>' found! Tag: " + cmd); printListError(WARN_DOXYGEN_HTML_ERROR, "Doxygen HTML error for tag " + cmd + ": HTML tag without '>' found.");
} }
// add args of HTML command, like link URL, image URL, ... // add args of HTML command, like link URL, image URL, ...
m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos, endHtmlPos - pos))); m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos, endHtmlPos - pos)));
@ -1268,7 +1267,7 @@ size_t DoxygenParser::processNormalComment(size_t pos, const std::string &line)
break; break;
default: default:
m_tokenListIt = m_tokenList.end(); m_tokenListIt = m_tokenList.end();
printListError(WARN_DOXYGEN_COMMAND_ERROR, std::string("Unknown special character: ") + line[pos]); printListError(WARN_DOXYGEN_UNKNOWN_CHARACTER, std::string("Unknown special character in Doxygen comment: ") + line[pos] + ".");
} }
return pos; return pos;
@ -1418,5 +1417,5 @@ void DoxygenParser::printListError(int warningType, const std::string &message)
} }
} }
Swig_warning(warningType, m_fileName.c_str(), curLine, "Doxygen parser warning: %s.\n", message.c_str()); Swig_warning(warningType, m_fileName.c_str(), curLine, "%s\n", message.c_str());
} }

3
Source/Include/swigwarn.h
View file

@ -214,8 +214,9 @@
#define WARN_DOXYGEN_UNKNOWN_COMMAND 560 #define WARN_DOXYGEN_UNKNOWN_COMMAND 560
#define WARN_DOXYGEN_UNEXPECTED_END_OF_COMMENT 561 #define WARN_DOXYGEN_UNEXPECTED_END_OF_COMMENT 561
#define WARN_DOXYGEN_COMMAND_EXPECTED 562 #define WARN_DOXYGEN_COMMAND_EXPECTED 562
#define WARN_DOXYGEN_UNTERMINATED_STRING 563 #define WARN_DOXYGEN_HTML_ERROR 563
#define WARN_DOXYGEN_COMMAND_ERROR 564 #define WARN_DOXYGEN_COMMAND_ERROR 564
#define WARN_DOXYGEN_UNKNOWN_CHARACTER 565
/* -- Reserved (600-799) -- */ /* -- Reserved (600-799) -- */