From bf2ee59a28d7b52c818b643da3165f3dab161489 Mon Sep 17 00:00:00 2001 From: Mikhail Golubev Date: Tue, 15 May 2018 00:27:19 +0300 Subject: [PATCH] PY-29717 Move message about copied docstring to sections --- .../com/jetbrains/python/PyBundle.properties | 6 +-- .../documentation/PyDocumentationBuilder.java | 41 ++++++------------- .../ClassUndocumentedConstructor.html | 2 +- .../ClassUndocumentedEmptyConstructor.html | 2 +- python/testData/quickdoc/InheritedMethod.html | 2 +- ...eferenceToMethodQualifiedWithInstance.html | 2 +- 6 files changed, 19 insertions(+), 36 deletions(-) diff --git a/python/src/com/jetbrains/python/PyBundle.properties b/python/src/com/jetbrains/python/PyBundle.properties index 8b6df3c846a3..48da94f870f2 100644 --- a/python/src/com/jetbrains/python/PyBundle.properties +++ b/python/src/com/jetbrains/python/PyBundle.properties @@ -797,13 +797,11 @@ PARSE.expected.@.or.def='@' or 'def' expected PARSE.expected.formal.param.name=formal parameter name expected ### qiuck doc generator -QDOC.copied.from.$0.$1=Documentation is missing. The following is copied from {0}.{1}. -QDOC.copied.from.builtin=(copied from built-in description) -QDOC.copied.from.class.$0=Documentation is missing. The following is copied from class {0}. QDOC.module.path.unknown=(Module path is unknown) QDOC.epydoc.python2.sdk.not.found=You need configured Python 2 SDK to render Epydoc docstrings QDOC.local.sdk.not.found=You need a configured local Python SDK to render docstrings. -QDOC.assigned.to=Assigned to +QDOC.assigned.to=Assigned to: +QDOC.documentation.is.copied.from=Documentation is copied from: runcfg.tests.cant_rerun=Can't rerun tests since test IDs can't be resolved. Try to delete run configuration, and create new one using right click. diff --git a/python/src/com/jetbrains/python/documentation/PyDocumentationBuilder.java b/python/src/com/jetbrains/python/documentation/PyDocumentationBuilder.java index 64e743cc5b9c..1512ac6fbf77 100644 --- a/python/src/com/jetbrains/python/documentation/PyDocumentationBuilder.java +++ b/python/src/com/jetbrains/python/documentation/PyDocumentationBuilder.java @@ -301,9 +301,8 @@ public class PyDocumentationBuilder { PyClass pyClass = null; final PyFunction pyFunction; final PyStringLiteralExpression docStringExpression = getEffectiveDocStringExpression(elementDefinition); - ChainIterable content = new ChainIterable<>(); if (docStringExpression != null) { - content = formatDocString(myElement, docStringExpression.getStringValue()); + myContent.add(formatDocString(myElement, docStringExpression.getStringValue())); } final TypeEvalContext context = TypeEvalContext.userInitiated(elementDefinition.getProject(), elementDefinition.getContainingFile()); @@ -328,7 +327,7 @@ public class PyDocumentationBuilder { myBody.add(PythonDocumentationProvider.describeDecorators(pyFunction, WRAP_IN_ITALIC, ESCAPE_AND_SAVE_NEW_LINES_AND_SPACES, BR, BR)); myBody.add(PythonDocumentationProvider.describeFunction(pyFunction, WRAP_IN_BOLD, ESCAPE_AND_SAVE_NEW_LINES_AND_SPACES, context)); if (docStringExpression == null) { - content = addInheritedDocString(pyFunction, pyClass); + addInheritedDocString(pyFunction, pyClass); } } else if (elementDefinition instanceof PyFile) { @@ -347,10 +346,6 @@ public class PyDocumentationBuilder { } myBody.add(PythonDocumentationProvider.describeTarget(target, context)); } - - if (content != null && !content.isEmpty()) { - myContent.add(content); - } } private boolean isAttribute() { @@ -380,11 +375,10 @@ public class PyDocumentationBuilder { return resolveResult.isImplicit() ? null : resolveResult.getElement(); } - @Nullable - private static ChainIterable addInheritedDocString(@NotNull final PyFunction pyFunction, @Nullable final PyClass pyClass) { + private void addInheritedDocString(@NotNull final PyFunction pyFunction, @Nullable final PyClass pyClass) { final String methodName = pyFunction.getName(); if (pyClass == null || methodName == null) { - return null; + return; } final boolean isConstructor = PyNames.INIT.equals(methodName); Iterable classes = pyClass.getAncestorClasses(null); @@ -409,8 +403,6 @@ public class PyDocumentationBuilder { if (docstringElement != null) { final String inheritedDoc = docstringElement.getStringValue(); if (inheritedDoc.length() > 1) { - ChainIterable result = new ChainIterable<>(); - result.addItem(BR).addItem(BR); final String ancestorName = ancestor.getName(); final String ancestorQualifiedName = ancestor.getQualifiedName(); final TypeEvalContext context = TypeEvalContext.userInitiated(pyFunction.getProject(), pyFunction.getContainingFile()); @@ -420,15 +412,12 @@ public class PyDocumentationBuilder { : ancestorName != null && ancestorQualifiedName != null ? PyDocumentationLink.toPossibleClass(ancestorName, ancestorQualifiedName, pyClass, context) : null; - if (isFromClass) { - result.addItem(PyBundle.message("QDOC.copied.from.class.$0", ancestorLink)); + if (ancestorLink != null) { + final ChainIterable link = mySectionsMap.get(PyBundle.message("QDOC.documentation.is.copied.from")); + link.addWith(TagCode, isFromClass ? $(ancestorLink) : $(ancestorLink).addItem("." + methodName)); } - else { - result.addItem(PyBundle.message("QDOC.copied.from.$0.$1", ancestorLink, methodName)); - } - result.addItem(BR).addItem(BR); - result.add(formatDocString(pyFunction, inheritedDoc)); - return result; + myContent.add(formatDocString(pyFunction, inheritedDoc)); + return; } } } @@ -437,13 +426,11 @@ public class PyDocumentationBuilder { // for well-known methods, copy built-in doc string. // TODO: also handle predefined __xxx__ that are not part of 'object'. if (PyNames.UNDERSCORED_ATTRIBUTES.contains(methodName)) { - return addPredefinedMethodDoc(pyFunction, methodName); + addPredefinedMethodDoc(pyFunction, methodName); } - return null; } - @Nullable - private static ChainIterable addPredefinedMethodDoc(@NotNull PyFunction fun, @NotNull String methodName) { + private void addPredefinedMethodDoc(@NotNull PyFunction fun, @NotNull String methodName) { final PyClassType objectType = PyBuiltinCache.getInstance(fun).getObjectType(); // old- and new-style classes share the __xxx__ stuff if (objectType != null) { final PyClass objectClass = objectType.getPyClass(); @@ -452,13 +439,11 @@ public class PyDocumentationBuilder { final PyStringLiteralExpression predefinedDocstring = getEffectiveDocStringExpression(predefinedMethod); final String predefinedDoc = predefinedDocstring != null ? predefinedDocstring.getStringValue() : null; if (predefinedDoc != null && predefinedDoc.length() > 1) { // only a real-looking doc string counts - ChainIterable result = formatDocString(fun, predefinedDoc); - result.addItem(BR).addItem(BR).addItem(PyBundle.message("QDOC.copied.from.builtin")); - return result; + mySectionsMap.get(PyBundle.message("QDOC.documentation.is.copied.from")).addItem("built-in description"); + myContent.add(formatDocString(fun, predefinedDoc)); } } } - return null; } @NotNull diff --git a/python/testData/quickdoc/ClassUndocumentedConstructor.html b/python/testData/quickdoc/ClassUndocumentedConstructor.html index 910756fe53d1..2389a7e4bca4 100644 --- a/python/testData/quickdoc/ClassUndocumentedConstructor.html +++ b/python/testData/quickdoc/ClassUndocumentedConstructor.html @@ -1 +1 @@ -
class Foo(object)

def __init__(self: Foo) -> None


Documentation is missing. The following is copied from class Foo.

Doc of Foo.
\ No newline at end of file +
class Foo(object)

def __init__(self: Foo) -> None
Doc of Foo.

Documentation is copied from:

Foo
\ No newline at end of file diff --git a/python/testData/quickdoc/ClassUndocumentedEmptyConstructor.html b/python/testData/quickdoc/ClassUndocumentedEmptyConstructor.html index fbdcbf884436..245940f8064b 100644 --- a/python/testData/quickdoc/ClassUndocumentedEmptyConstructor.html +++ b/python/testData/quickdoc/ClassUndocumentedEmptyConstructor.html @@ -1 +1 @@ -
class Foo(Moo)

def __init__(self: Foo) -> None


Documentation is missing. The following is copied from Moo.__init__.

Doc of Moo()
\ No newline at end of file +
class Foo(Moo)

def __init__(self: Foo) -> None
Doc of Moo()

Documentation is copied from:

Moo.__init__
\ No newline at end of file diff --git a/python/testData/quickdoc/InheritedMethod.html b/python/testData/quickdoc/InheritedMethod.html index 58ece77fa315..01592659c985 100644 --- a/python/testData/quickdoc/InheritedMethod.html +++ b/python/testData/quickdoc/InheritedMethod.html @@ -1 +1 @@ -
class B(A)

def foo(self: B) -> None


Documentation is missing. The following is copied from A.foo.

Doc from A.foo.
\ No newline at end of file +
class B(A)

def foo(self: B) -> None
Doc from A.foo.

Documentation is copied from:

A.foo
\ No newline at end of file diff --git a/python/testData/quickdoc/ReferenceToMethodQualifiedWithInstance.html b/python/testData/quickdoc/ReferenceToMethodQualifiedWithInstance.html index 214fb4d9539b..e3e5588841db 100644 --- a/python/testData/quickdoc/ReferenceToMethodQualifiedWithInstance.html +++ b/python/testData/quickdoc/ReferenceToMethodQualifiedWithInstance.html @@ -1 +1 @@ -
class list(MutableSequence[_T], Generic[_T])

def count(self: list, object: _T) -> int
L.count(value) -> integer -- return number of occurrences of value 

Assigned to

c1
\ No newline at end of file +
class list(MutableSequence[_T], Generic[_T])

def count(self: list, object: _T) -> int
L.count(value) -> integer -- return number of occurrences of value 

Assigned to:

c1
\ No newline at end of file