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

Document the return type when translating Doxygen @return to Python.

Browse source 
In addition to translating the comment itself, also document the type of the
object returned. This is consistent with generating not only :param: but also
:type: for the parameters documented using @param.
This commit is contained in:
Vadim Zeitlin 2014-08-11 16:22:48 +02:00
commit 6aa9cd37a5
4 changed files with 49 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

63
Source/DoxygenTranslator/src/PyDocConverter.cpp
View file

@ -334,6 +334,38 @@ PyDocConverter::PyDocConverter(int flags) :
fillStaticTables();
}
// Return the type as it should appear in the output documentation.
static
std::string getPyDocType(Node* n, const_String_or_char_ptr lname = "")
{
std::string type;
String *s = Swig_typemap_lookup("doctype", n, lname, 0);
if (!s)
s = SwigType_str(Getattr(n, "type"), "");
if (Language::classLookup(s)) {
// In Python C++ namespaces are flattened, so remove all but last component
// of the name.
String * const last = Swig_scopename_last(s);
// We are not actually sure whether it's a documented class or not, but
// there doesn't seem to be any harm in making it a reference if it isn't,
// while there is a lot of benefit in having a hyperlink if it is.
type = ":py:class:`";
type += Char (last);
type += "`";
Delete(last);
} else {
type = Char(s);
}
Delete(s);
return type;
}
std::string PyDocConverter::getParamType(std::string param)
{
std::string type;
@ -344,28 +376,7 @@ std::string PyDocConverter::getParamType(std::string param)
if (Char (pname) != param)
continue;
String *s = Swig_typemap_lookup("doctype", p, pname, 0);
if (!s)
s = SwigType_str(Getattr(p, "type"), "");
if (Language::classLookup(s)) {
// In Python C++ namespaces are flattened, so remove all but last component
// of the name.
String * const last = Swig_scopename_last(s);
// We are not actually sure whether it's a documented class or not, but
// there doesn't seem to be any harm in making it a reference if it isn't,
// while there is a lot of benefit in having a hyperlink if it is.
type = ":py:class:`";
type += Char (last);
type += "`";
Delete(last);
} else {
type = Char(s);
}
Delete(s);
type = getPyDocType(p, pname);
break;
}
Delete(plist);
@ -619,6 +630,14 @@ void PyDocConverter::handleTagReturn(DoxygenEntity &tag,
{
IndentGuard indent(translatedComment, m_indent);
const std::string pytype = getPyDocType(currentNode);
if (!pytype.empty()) {
translatedComment += ":rtype: ";
translatedComment += pytype;
translatedComment += "\n";
translatedComment += indent.getFirstLineIndent();
}
translatedComment += ":return: ";
handleParagraph(tag, translatedComment);
}