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

Give warnings for unknown Doxygen commands in Doxygen parser.

Browse source 
Silently ignoring unknown Doxygen commands is not a reasonable default
behaviour, it's simple enough to turn off the warning if the command is really
supposed to be just ignored, but it's too easy to not notice a real problem if
it isn't.

Turn WARN_DOXYGEN_UNKNOWN_COMMAND on by default and add a test to the errors
test suite checking that it is indeed given.
This commit is contained in:
Vadim Zeitlin 2014-08-22 22:44:55 +02:00
commit a1d7930835
5 changed files with 39 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Examples/test-suite/doxygen_misc_constructs.i
View file

@ -3,6 +3,8 @@
%module doxygen_misc_constructs
%warnfilter(SWIGWARN_DOXYGEN_UNKNOWN_COMMAND) backslashB;
%inline %{
// Tag '@endink' must be recognized even if it is not

14
Examples/test-suite/errors/Makefile.in
View file

@ -24,12 +24,24 @@ top_builddir = @top_builddir@
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 OSX behaves as if written 's/r$$//'

6
Examples/test-suite/errors/doxygen_unknown_command.i Normal file
View file

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

1
Examples/test-suite/errors/doxygen_unknown_command.stderr Normal file
View file

@ -0,0 +1 @@
doxygen_unknown_command.i:4: Warning 720: Doxygen parser warning: unknown command "unknown".

23
Source/DoxygenTranslator/src/DoxygenParser.cpp
View file

@ -1028,11 +1028,22 @@ bool DoxygenParser::addDoxyCommand(DoxygenParser::TokenList &tokList,
tokList.push_back(Token(COMMAND, cmd));
return true;
} else {
// Unknown commands are ignored, because they are
// also ignored by Doxygen - see test doxygen_misc_constructs.h, f. backslashB().
// This differs from original implementation in this class. Uncomment
// the line below to put unknown commands to output.
// tokList.push_back(Token(PLAINSTRING, cmd));
// This function is called for the special Doxygen commands, but also for
// HTML commands (or anything that looks like them, actually) and entities.
// We don't recognize all of those, so just ignore them and pass them
// through, but warn about unknown Doxygen commands as ignoring them will
// often result in wrong output being generated.
const char ch = *cmd.begin();
if (ch != '<' && ch != '&') {
// Before calling printListError() we must ensure that m_tokenListIt used
// by it is valid.
const TokenListCIt itSave = m_tokenListIt;
m_tokenListIt = m_tokenList.end();
printListError(WARN_DOXYGEN_UNKNOWN_COMMAND, "unknown command \"" + cmd + '"');
m_tokenListIt = itSave;
}
}
return false;
@ -1431,5 +1442,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());
"Doxygen parser warning: %s.\n", message.c_str());
}