From 065ce992dcb0927e2f80f6fa12c370fac5d1a8cd Mon Sep 17 00:00:00 2001 From: Mikhail Golubev Date: Mon, 14 May 2018 23:46:03 +0300 Subject: [PATCH] PY-29717 Wrap both prolog and body in
block --- .../documentation/PyDocumentationBuilder.java | 31 +++++++++++-------- python/testData/quickdoc/ClassAttr.html | 2 +- python/testData/quickdoc/InstanceAttr.html | 2 +- python/testData/quickdoc/Module.html | 2 +- python/testData/quickdoc/Param.html | 2 +- python/testData/quickdoc/PropNewDeleter.html | 2 +- python/testData/quickdoc/PropNewGetter.html | 2 +- python/testData/quickdoc/PropNewSetter.html | 2 +- python/testData/quickdoc/PropOldDeleter.html | 2 +- python/testData/quickdoc/PropOldGetter.html | 2 +- python/testData/quickdoc/PropOldSetter.html | 2 +- 11 files changed, 28 insertions(+), 23 deletions(-) diff --git a/python/src/com/jetbrains/python/documentation/PyDocumentationBuilder.java b/python/src/com/jetbrains/python/documentation/PyDocumentationBuilder.java index 1fb9e626a5ae..64e743cc5b9c 100644 --- a/python/src/com/jetbrains/python/documentation/PyDocumentationBuilder.java +++ b/python/src/com/jetbrains/python/documentation/PyDocumentationBuilder.java @@ -69,9 +69,9 @@ import static com.jetbrains.python.documentation.DocumentationBuilderKit.*; public class PyDocumentationBuilder { private final PsiElement myElement; private final PsiElement myOriginalElement; - private ChainIterable myResult; private final ChainIterable myProlog; // sequence for reassignment info, etc private final ChainIterable myBody; // sequence for doc string + private final ChainIterable myContent; private final ChainIterable mySections; private final ChainIterable myEpilog; // sequence for doc "copied from" notices and such @@ -82,15 +82,11 @@ public class PyDocumentationBuilder { public PyDocumentationBuilder(PsiElement element, PsiElement originalElement) { myElement = element; myOriginalElement = originalElement; - myResult = new ChainIterable<>(); myProlog = new ChainIterable<>(); myBody = new ChainIterable<>(); + myContent = new ChainIterable<>(); mySections = new ChainIterable<>(); myEpilog = new ChainIterable<>(); - - - myResult.add(myProlog).add(myBody).add(mySections).add(myEpilog); // pre-assemble; then add stuff to individual cats as needed - myResult = wrapInTag("html", wrapInTag("body", myResult)); } @Nullable @@ -144,11 +140,24 @@ public class PyDocumentationBuilder { myEpilog.addItem("").addItem(url).addItem(""); } - if (myBody.isEmpty() && myEpilog.isEmpty()) { + if (myBody.isEmpty() && myContent.isEmpty() && myEpilog.isEmpty()) { return null; // got nothing substantial to say! } else { - return myResult.toString(); + ChainIterable result = new ChainIterable<>(); + if (!myProlog.isEmpty() || !myBody.isEmpty()) { + result.addItem(DocumentationMarkup.DEFINITION_START) + .add(myProlog) + .add(myBody) + .addItem(DocumentationMarkup.DEFINITION_END); + } + if (!myContent.isEmpty()) { + result.addItem(DocumentationMarkup.CONTENT_START) + .add(myContent) + .addItem(DocumentationMarkup.CONTENT_END); + } + result.add(mySections).add(myEpilog); // pre-assemble; then add stuff to individual cats as needed + return wrapInTag("html", wrapInTag("body", result)).toString(); } } @@ -297,7 +306,6 @@ public class PyDocumentationBuilder { content = formatDocString(myElement, docStringExpression.getStringValue()); } final TypeEvalContext context = TypeEvalContext.userInitiated(elementDefinition.getProject(), elementDefinition.getContainingFile()); - myBody.addItem(DocumentationMarkup.DEFINITION_START); if (elementDefinition instanceof PyClass) { pyClass = (PyClass)elementDefinition; @@ -340,11 +348,8 @@ public class PyDocumentationBuilder { myBody.add(PythonDocumentationProvider.describeTarget(target, context)); } - myBody.addItem(DocumentationMarkup.DEFINITION_END); if (content != null && !content.isEmpty()) { - myBody.addItem(DocumentationMarkup.CONTENT_START); - myBody.add(content); - myBody.addItem(DocumentationMarkup.CONTENT_END); + myContent.add(content); } } diff --git a/python/testData/quickdoc/ClassAttr.html b/python/testData/quickdoc/ClassAttr.html index 000169175ff1..cefb3ebbbf9a 100644 --- a/python/testData/quickdoc/ClassAttr.html +++ b/python/testData/quickdoc/ClassAttr.html @@ -1 +1 @@ -Class attribute the_attr of class C
the_attr: str
The documentation for the attribute. 
\ No newline at end of file +
Class attribute the_attr of class C
the_attr: str
The documentation for the attribute. 
\ No newline at end of file diff --git a/python/testData/quickdoc/InstanceAttr.html b/python/testData/quickdoc/InstanceAttr.html index c377ec26d40d..b56712e4e704 100644 --- a/python/testData/quickdoc/InstanceAttr.html +++ b/python/testData/quickdoc/InstanceAttr.html @@ -1 +1 @@ -Instance attribute foo of class C
foo: str
The docstring for the attribute foo. 
\ No newline at end of file +
Instance attribute foo of class C
foo: str
The docstring for the attribute foo. 
\ No newline at end of file diff --git a/python/testData/quickdoc/Module.html b/python/testData/quickdoc/Module.html index 1da918ec976f..c7f14ccb8ad8 100644 --- a/python/testData/quickdoc/Module.html +++ b/python/testData/quickdoc/Module.html @@ -1 +1 @@ -Module Module

Module's doc.

\ No newline at end of file
+
Module Module

Module's doc.

\ No newline at end of file
diff --git a/python/testData/quickdoc/Param.html b/python/testData/quickdoc/Param.html
index de1239f0d14b..c18b85f64f2d 100644
--- a/python/testData/quickdoc/Param.html
+++ b/python/testData/quickdoc/Param.html
@@ -1 +1 @@
-Parameter name: str
The name to convert to a label.  This must be a string which could be used as a Python identifier.  Strings which do not take this form will result in unpredictable behavior.
\ No newline at end of file
+
Parameter name: str

The name to convert to a label.  This must be a string which could be used as a Python identifier.  Strings which do not take this form will result in unpredictable behavior.
\ No newline at end of file
diff --git a/python/testData/quickdoc/PropNewDeleter.html b/python/testData/quickdoc/PropNewDeleter.html
index 0eedcdf7c030..c4aaa67762f1 100644
--- a/python/testData/quickdoc/PropNewDeleter.html
+++ b/python/testData/quickdoc/PropNewDeleter.html
@@ -1 +1 @@
-property x of class A(object)
Copied from getter:
Does things to X

@x.deleter
def x(self: A, v: Any) -> None
Deletes X


Deleter of property

\ No newline at end of file
+
property x of class A(object)
Copied from getter:
Does things to X

@x.deleter
def x(self: A, v: Any) -> None
Deletes X


Deleter of property

\ No newline at end of file
diff --git a/python/testData/quickdoc/PropNewGetter.html b/python/testData/quickdoc/PropNewGetter.html
index 33161996b769..fd37232e6c51 100644
--- a/python/testData/quickdoc/PropNewGetter.html
+++ b/python/testData/quickdoc/PropNewGetter.html
@@ -1 +1 @@
-property x of class A(object)

@property
def x(self: A) -> int
Does things to X


Getter of property

\ No newline at end of file
+
property x of class A(object)

@property
def x(self: A) -> int
Does things to X


Getter of property

\ No newline at end of file
diff --git a/python/testData/quickdoc/PropNewSetter.html b/python/testData/quickdoc/PropNewSetter.html
index 9c4c28a9d253..2896e8cc3494 100644
--- a/python/testData/quickdoc/PropNewSetter.html
+++ b/python/testData/quickdoc/PropNewSetter.html
@@ -1 +1 @@
-property x of class A(object)
Copied from getter:
Does things to X

@x.setter
def x(self: A, v: Any) -> None
Sets X


Setter of property

\ No newline at end of file
+
property x of class A(object)
Copied from getter:
Does things to X

@x.setter
def x(self: A, v: Any) -> None
Sets X


Setter of property

\ No newline at end of file
diff --git a/python/testData/quickdoc/PropOldDeleter.html b/python/testData/quickdoc/PropOldDeleter.html
index ed7b7f2331c1..52faea723152 100644
--- a/python/testData/quickdoc/PropOldDeleter.html
+++ b/python/testData/quickdoc/PropOldDeleter.html
@@ -1 +1 @@
-property x of class A(object)

def __getX(self: A) -> Any
Doc of getter


Deleter of property

\ No newline at end of file
+
property x of class A(object)

def __getX(self: A) -> Any
Doc of getter


Deleter of property

\ No newline at end of file
diff --git a/python/testData/quickdoc/PropOldGetter.html b/python/testData/quickdoc/PropOldGetter.html
index f804cfc2b10f..e42b92f76da3 100644
--- a/python/testData/quickdoc/PropOldGetter.html
+++ b/python/testData/quickdoc/PropOldGetter.html
@@ -1 +1 @@
-property x of class A(object)

def __getX(self: A) -> Any
Doc of getter


Getter of property

\ No newline at end of file
+
property x of class A(object)

def __getX(self: A) -> Any
Doc of getter


Getter of property

\ No newline at end of file
diff --git a/python/testData/quickdoc/PropOldSetter.html b/python/testData/quickdoc/PropOldSetter.html
index 1a6b0fdd2e70..b1c9d090ab50 100644
--- a/python/testData/quickdoc/PropOldSetter.html
+++ b/python/testData/quickdoc/PropOldSetter.html
@@ -1 +1 @@
-property x of class A(object)

def __getX(self: A, x: Any) -> None
Doc of getter


Setter of property

\ No newline at end of file
+
property x of class A(object)

def __getX(self: A, x: Any) -> None
Doc of getter


Setter of property

\ No newline at end of file