diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py index dfc6688d0..080f47c92 100644 --- a/Examples/test-suite/python/doxygen_basic_translate_runme.py +++ b/Examples/test-suite/python/doxygen_basic_translate_runme.py @@ -13,7 +13,7 @@ commentVerifier.check(doxygen_basic_translate.function.__doc__, Author: Some author - Return: Some number + :return: Some number See also: function2 """ @@ -65,15 +65,15 @@ commentVerifier.check(doxygen_basic_translate.function5.__doc__, commentVerifier.check(doxygen_basic_translate.function6.__doc__, """ Test for default args - Arguments: - a (int) -- Some parameter, default is 42 + :type a: int + :param a: Some parameter, default is 42 """ ) commentVerifier.check(doxygen_basic_translate.function7.__doc__, """ Test for a parameter with difficult type (mostly for python) - Arguments: - a (Shape::superType *[10]) -- Very strange param + :type a: Shape::superType *[10] + :param a: Very strange param """ ) diff --git a/Examples/test-suite/python/doxygen_misc_constructs_runme.py b/Examples/test-suite/python/doxygen_misc_constructs_runme.py index 1517a7279..38a2baf2b 100644 --- a/Examples/test-suite/python/doxygen_misc_constructs_runme.py +++ b/Examples/test-suite/python/doxygen_misc_constructs_runme.py @@ -10,10 +10,12 @@ commentVerifier.check(doxygen_misc_constructs.getAddress.__doc__, r""" Returns address of file line. - Arguments: - fileName (int &) -- name of the file, where the source line is located - line (int) -- line number - isGetSize (bool) -- if set, for every object location both address and size are returned + :type fileName: int & + :param fileName: name of the file, where the source line is located + :type line: int + :param line: line number + :type isGetSize: bool + :param isGetSize: if set, for every object location both address and size are returned Connection::getId() @@ -127,8 +129,8 @@ commentVerifier.check(doxygen_misc_constructs.cycle.__doc__, Similar __for__: double colon. Spaces at the start of line should be taken into account: - Arguments: - id (int) -- used as prefix in log + :type id: int + :param id: used as prefix in log statements. The default value is empty string, which is OK if there is only one app. instance. Example: @@ -139,6 +141,7 @@ commentVerifier.check(doxygen_misc_constructs.cycle.__doc__, main_ctrl.setBP("func1"); - fileName (char *) -- name of the log file + :type fileName: char * + :param fileName: name of the log file """ ); diff --git a/Examples/test-suite/python/doxygen_parsing_runme.py b/Examples/test-suite/python/doxygen_parsing_runme.py index 7b4e03424..1e5dd7e00 100644 --- a/Examples/test-suite/python/doxygen_parsing_runme.py +++ b/Examples/test-suite/python/doxygen_parsing_runme.py @@ -27,18 +27,20 @@ commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended.__doc r""" The class method with parameter - Arguments: - a (int) -- Parameter a - b (int) -- Parameter b + :type a: int + :param a: Parameter a + :type b: int + :param b: Parameter b """ ) commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended2.__doc__, r""" The class method with parameter - Arguments: - a (int) -- Parameter a - b (int) -- Parameter b + :type a: int + :param a: Parameter a + :type b: int + :param b: Parameter b """ ) commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethod.__doc__, @@ -49,16 +51,18 @@ commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended.__d r""" The struct method with parameter - Arguments: - a (int) -- Parameter a - b (int) -- Parameter b + :type a: int + :param a: Parameter a + :type b: int + :param b: Parameter b """ ) commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended2.__doc__, r""" The struct method with parameter - Arguments: - a (int) -- Parameter a - b (int) -- Parameter b + :type a: int + :param a: Parameter a + :type b: int + :param b: Parameter b """) diff --git a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py index f1263f39e..0128ca5aa 100644 --- a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py +++ b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py @@ -79,7 +79,7 @@ r""" _italicword_ - emphazedWord + emphazedWord @@ -89,7 +89,7 @@ r""" commentVerifier.check(doxygen_translate_all_tags.func04.__doc__, r""" - Throws: SuperError + :raises: SuperError @@ -219,8 +219,8 @@ r""" - Arguments: - a (int) -- the first param + :type a: int + :param a: the first param @@ -255,11 +255,11 @@ r""" Another remarks section - Return: Whatever + :return: Whatever - it + :return: it - Returns: may return + :return: may return """) @@ -295,17 +295,17 @@ r""" - Throw: superException + :raises: superException - Throws: RuntimeError + :raises: RuntimeError """) commentVerifier.check(doxygen_translate_all_tags.func10.__doc__, r""" TODO: Some very important task - Arguments: - b (float) -- B is mentioned again... + :type b: float + :param b: B is mentioned again... diff --git a/Examples/test-suite/python/doxygen_translate_runme.py b/Examples/test-suite/python/doxygen_translate_runme.py index 4e2338124..2b22c7380 100644 --- a/Examples/test-suite/python/doxygen_translate_runme.py +++ b/Examples/test-suite/python/doxygen_translate_runme.py @@ -37,7 +37,7 @@ r""" Example: someFile.txt Some details on using the example - Throws: SuperError + :raises: SuperError If: ANOTHERCONDITION { First part of comment @@ -88,18 +88,18 @@ r""" The paragraph text. Maybe even multiline - Arguments: - a (int) -- the first param + :type a: int + :param a: the first param Remarks: Some remark text Another remarks section - Return: Whatever + :return: Whatever - it + :return: it - Returns: may return + :return: may return See also: someOtherMethod @@ -107,14 +107,14 @@ r""" Since: version 0.0.0.1 - Throw: superException + :raises: superException - Throws: RuntimeError + :raises: RuntimeError TODO: Some very important task - Arguments: - b (float) -- B is mentioned again... + :type b: float + :param b: B is mentioned again... very long @@ -225,8 +225,8 @@ commentVerifier.check(doxygen_translate.htmlTableFunction.__doc__, r""" The meaning of flags: - Arguments: - byFlags (int) -- bits marking required items: + :type byFlags: int + :param byFlags: bits marking required items: | Size in bits| Items Required | -------------------------------- diff --git a/Source/DoxygenTranslator/src/PyDocConverter.cpp b/Source/DoxygenTranslator/src/PyDocConverter.cpp index dee98a873..ee9535953 100644 --- a/Source/DoxygenTranslator/src/PyDocConverter.cpp +++ b/Source/DoxygenTranslator/src/PyDocConverter.cpp @@ -50,21 +50,13 @@ void PyDocConverter::fillStaticTables() sectionTitles["copyright"] = "Copyright: "; sectionTitles["deprecated"] = "Deprecated: "; sectionTitles["example"] = "Example: "; - sectionTitles["exception"] = "Throws: "; - sectionTitles["param"] = "Arguments:\n"; - sectionTitles["tparam"] = "Arguments:\n"; sectionTitles["note"] = "Notes: "; sectionTitles["remark"] = "Remarks: "; sectionTitles["remarks"] = "Remarks: "; sectionTitles["warning"] = "Warning: "; - sectionTitles["result"] = "Return: "; - sectionTitles["return"] = "Return: "; - sectionTitles["returns"] = "Returns: "; // sectionTitles["sa"] = "See also: "; // sectionTitles["see"] = "See also: "; sectionTitles["since"] = "Since: "; - sectionTitles["throw"] = "Throw: "; - sectionTitles["throws"] = "Throws: "; sectionTitles["todo"] = "TODO: "; sectionTitles["version"] = "Version: "; @@ -100,7 +92,9 @@ void PyDocConverter::fillStaticTables() tagHandlers["details"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["em"] = make_handler(&PyDocConverter::handleParagraph, " "); tagHandlers["example"] = make_handler(&PyDocConverter::handleParagraph); - tagHandlers["exception"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["exception"] = + tagHandlers["throw"] = + tagHandlers["throws"] = make_handler(&PyDocConverter::handleTagException); tagHandlers["htmlonly"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["invariant"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["latexonly"] = make_handler(&PyDocConverter::handleParagraph); @@ -110,9 +104,6 @@ void PyDocConverter::fillStaticTables() tagHandlers["p"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["partofdescription"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["rtfonly"] = make_handler(&PyDocConverter::handleParagraph); - tagHandlers["return"] = make_handler(&PyDocConverter::handleParagraph); - tagHandlers["returns"] = make_handler(&PyDocConverter::handleParagraph); - tagHandlers["result"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["remark"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["remarks"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["sa"] = make_handler(&PyDocConverter::handleTagMessage, "See also: "); @@ -120,8 +111,6 @@ void PyDocConverter::fillStaticTables() "See also: "); tagHandlers["since"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["short"] = make_handler(&PyDocConverter::handleParagraph); - tagHandlers["throw"] = make_handler(&PyDocConverter::handleParagraph); - tagHandlers["throws"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["todo"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["version"] = make_handler(&PyDocConverter::handleParagraph); tagHandlers["verbatim"] = make_handler(&PyDocConverter::handleParagraph); @@ -144,9 +133,13 @@ void PyDocConverter::fillStaticTables() " convenience.\nIt differs from the above function only in what" " argument(s) it accepts."); tagHandlers["par"] = make_handler(&PyDocConverter::handleTagPar); - tagHandlers["param"] = make_handler(&PyDocConverter::handleTagParam); + tagHandlers["param"] = tagHandlers["tparam"] = make_handler(&PyDocConverter::handleTagParam); tagHandlers["ref"] = make_handler(&PyDocConverter::handleTagRef); + tagHandlers["result"] = + tagHandlers["return"] = + tagHandlers["returns"] = make_handler(&PyDocConverter::handleTagReturn); + // this command just prints it's contents // (it is internal command of swig's parser, contains plain text) tagHandlers["plainstd::string"] = make_handler(&PyDocConverter::handlePlainString); @@ -417,11 +410,31 @@ void PyDocConverter::handleTagParam(DoxygenEntity& tag, DoxygenEntity paramNameEntity = *tag.entityList.begin(); tag.entityList.pop_front(); - std::string paramType = getParamType(paramNameEntity.data); - if (!paramType.size()) - paramType = "none"; + const std::string& paramName = paramNameEntity.data; - translatedComment += " " + paramNameEntity.data + " (" + paramType + ") --"; + const std::string paramType = getParamType(paramName); + if (!paramType.empty()) + translatedComment += ":type " + paramName + ": " + paramType + "\n"; + + translatedComment += ":param " + paramName + ":"; + handleParagraph(tag, translatedComment); +} + + +void PyDocConverter::handleTagReturn(DoxygenEntity &tag, + std::string &translatedComment, + const std::string &) +{ + translatedComment += ":return: "; + handleParagraph(tag, translatedComment); +} + + +void PyDocConverter::handleTagException(DoxygenEntity &tag, + std::string &translatedComment, + const std::string &) +{ + translatedComment += ":raises: "; handleParagraph(tag, translatedComment); } diff --git a/Source/DoxygenTranslator/src/PyDocConverter.h b/Source/DoxygenTranslator/src/PyDocConverter.h index 921e1c09e..435c18c28 100644 --- a/Source/DoxygenTranslator/src/PyDocConverter.h +++ b/Source/DoxygenTranslator/src/PyDocConverter.h @@ -71,6 +71,10 @@ protected: * Print the name of tag to the output, used for escape-commands */ void handleTagChar(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + /* + * Format the contents of the \exception tag or its synonyms. + */ + void handleTagException(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); /* * Print only the content and strip original tag */ @@ -109,6 +113,10 @@ protected: * Format nice param description with type information */ void handleTagParam(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + /* + * Format the contents of the \return tag or its synonyms. + */ + void handleTagReturn(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); /* * Writes text for \ref tag. */