/**
* Adds type and description representation from function docstring
*
* @param parameter parameter of a function
* @return true if type from docstring was added
*/
private boolean addTypeAndDescriptionFromDocstring(@NotNull final PyNamedParameter parameter) {
final PyFunction function = PsiTreeUtil.getParentOfType(parameter, PyFunction.class);
if (function != null) {
final String docString = PyPsiUtils.strValue(function.getDocStringExpression());
final Pair<String, String> typeAndDescr = getTypeAndDescription(docString, parameter);
final String type = typeAndDescr.first;
final String description = typeAndDescr.second;
if (type != null) {
final PyType pyType = PyTypeParser.getTypeByName(parameter, type);
if (pyType instanceof PyClassType) {
myBody
.addItem(": ")
.addWith(
new LinkWrapper(PythonDocumentationProvider.LINK_TYPE_PARAM),
$(pyType.getName()));
} else {
myBody.addItem(": ").addItem(type);
}
}
if (description != null) {
myEpilog.addItem(BR).addItem(description);
}
return type != null;
}
return false;
}
private void buildFromDocstring(@NotNull final PsiElement elementDefinition, boolean isProperty) {
PyClass pyClass = null;
final PyStringLiteralExpression docStringExpression =
((PyDocStringOwner) elementDefinition).getDocStringExpression();
if (elementDefinition instanceof PyClass) {
pyClass = (PyClass) elementDefinition;
myBody.add(PythonDocumentationProvider.describeDecorators(pyClass, TagItalic, BR, LCombUp));
myBody.add(PythonDocumentationProvider.describeClass(pyClass, TagBold, true, false));
} else if (elementDefinition instanceof PyFunction) {
PyFunction pyFunction = (PyFunction) elementDefinition;
if (!isProperty) {
pyClass = pyFunction.getContainingClass();
if (pyClass != null) {
myBody
.addWith(
TagSmall, PythonDocumentationProvider.describeClass(pyClass, TagCode, true, true))
.addItem(BR)
.addItem(BR);
}
}
myBody
.add(PythonDocumentationProvider.describeDecorators(pyFunction, TagItalic, BR, LCombUp))
.add(PythonDocumentationProvider.describeFunction(pyFunction, TagBold, LCombUp));
if (docStringExpression == null) {
addInheritedDocString(pyFunction, pyClass);
}
} else if (elementDefinition instanceof PyFile) {
addModulePath((PyFile) elementDefinition);
}
if (docStringExpression != null) {
myBody.addItem(BR);
addFormattedDocString(myElement, docStringExpression.getStringValue(), myBody, myEpilog);
}
}
private void addPredefinedMethodDoc(PyFunction fun, String mothodName) {
PyClassType objectType =
PyBuiltinCache.getInstance(fun)
.getObjectType(); // old- and new-style classes share the __xxx__ stuff
if (objectType != null) {
PyClass objectClass = objectType.getPyClass();
PyFunction predefinedMethod = objectClass.findMethodByName(mothodName, false);
if (predefinedMethod != null) {
PyStringLiteralExpression predefinedDocstring = predefinedMethod.getDocStringExpression();
String predefinedDoc =
predefinedDocstring != null ? predefinedDocstring.getStringValue() : null;
if (predefinedDoc != null
&& predefinedDoc.length() > 1) { // only a real-looking doc string counts
addFormattedDocString(fun, predefinedDoc, myBody, myBody);
myEpilog.addItem(BR).addItem(BR).addItem(PyBundle.message("QDOC.copied.from.builtin"));
}
}
}
}
private void addInheritedDocString(
@NotNull final PyFunction pyFunction, @Nullable final PyClass pyClass) {
boolean notFound = true;
final String methodName = pyFunction.getName();
if (pyClass == null || methodName == null) {
return;
}
final boolean isConstructor = PyNames.INIT.equals(methodName);
Iterable<PyClass> classes = pyClass.getAncestorClasses(null);
if (isConstructor) {
// look at our own class again and maybe inherit class's doc
classes = new ChainIterable<PyClass>(pyClass).add(classes);
}
for (PyClass ancestor : classes) {
PyStringLiteralExpression docstringElement = null;
PyFunction inherited = null;
boolean isFromClass = false;
if (isConstructor) docstringElement = pyClass.getDocStringExpression();
if (docstringElement != null) {
isFromClass = true;
} else {
inherited = ancestor.findMethodByName(methodName, false);
}
if (inherited != null) {
docstringElement = inherited.getDocStringExpression();
}
if (docstringElement != null) {
final String inheritedDoc = docstringElement.getStringValue();
if (inheritedDoc.length() > 1) {
myEpilog.addItem(BR).addItem(BR);
String ancestor_name = ancestor.getName();
String marker =
(pyClass == ancestor)
? PythonDocumentationProvider.LINK_TYPE_CLASS
: PythonDocumentationProvider.LINK_TYPE_PARENT;
final String ancestor_link =
$().addWith(new LinkWrapper(marker + ancestor_name), $(ancestor_name)).toString();
if (isFromClass) {
myEpilog.addItem(PyBundle.message("QDOC.copied.from.class.$0", ancestor_link));
} else {
myEpilog.addItem(PyBundle.message("QDOC.copied.from.$0.$1", ancestor_link, methodName));
}
myEpilog.addItem(BR).addItem(BR);
ChainIterable<String> formatted = new ChainIterable<String>();
ChainIterable<String> unformatted = new ChainIterable<String>();
addFormattedDocString(pyFunction, inheritedDoc, formatted, unformatted);
myEpilog.addWith(TagCode, formatted).add(unformatted);
notFound = false;
break;
}
}
}
if (notFound) {
// above could have not worked because inheritance is not searched down to 'object'.
// for well-known methods, copy built-in doc string.
// TODO: also handle predefined __xxx__ that are not part of 'object'.
if (PyNames.UnderscoredAttributes.contains(methodName)) {
addPredefinedMethodDoc(pyFunction, methodName);
}
}
}