From 6d1ccc22ab7d736f85a26917e97017d71d88597a Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Wed, 29 Jul 2015 15:49:52 +0200 Subject: [PATCH] reduce vertical whitespace in rendered KDoc comments --- .../idea/KotlinQuickDocumentationProvider.kt | 8 +++++++- .../kotlin/idea/kdoc/KDocRenderer.kt | 20 +++++++++---------- .../quickDoc/KotlinClassUsedFromJava.java | 3 +-- .../editor/quickDoc/MethodFromStdLib.kt | 3 +-- .../OnClassDeclarationWithNoPackage.kt | 3 +-- .../OnFunctionDeclarationWithPackage.kt | 3 +-- .../editor/quickDoc/OnInheritedMethodUsage.kt | 3 +-- .../quickDoc/OnInheritedPropertyUsage.kt | 3 +-- .../testData/editor/quickDoc/OnMethodUsage.kt | 3 +-- .../editor/quickDoc/OnMethodUsageMultiline.kt | 3 +-- .../OnMethodUsageWithBracketsInParam.kt | 3 +-- .../quickDoc/OnMethodUsageWithCodeBlock.kt | 6 ++---- .../quickDoc/OnMethodUsageWithMarkdown.kt | 14 ++++--------- .../OnMethodUsageWithReturnAndThrows.kt | 3 +-- .../editor/quickDoc/OnMethodUsageWithSee.kt | 4 ++-- .../quickDoc/TopLevelMethodFromJava.java | 3 +-- 16 files changed, 35 insertions(+), 50 deletions(-) diff --git a/idea/src/org/jetbrains/kotlin/idea/KotlinQuickDocumentationProvider.kt b/idea/src/org/jetbrains/kotlin/idea/KotlinQuickDocumentationProvider.kt index c9bdee7cf3f..f84566e501c 100644 --- a/idea/src/org/jetbrains/kotlin/idea/KotlinQuickDocumentationProvider.kt +++ b/idea/src/org/jetbrains/kotlin/idea/KotlinQuickDocumentationProvider.kt @@ -130,7 +130,13 @@ public class KotlinQuickDocumentationProvider : AbstractDocumentationProvider() } val comment = KDocFinder.findKDoc(declarationDescriptor) if (comment != null) { - renderedDecl = renderedDecl + "
" + KDocRenderer.renderKDoc(comment) + val renderedComment = KDocRenderer.renderKDoc(comment) + if (renderedComment.startsWith("

")) { + renderedDecl += renderedComment + } + else { + renderedDecl = "$renderedDecl
$renderedComment" + } } return renderedDecl diff --git a/idea/src/org/jetbrains/kotlin/idea/kdoc/KDocRenderer.kt b/idea/src/org/jetbrains/kotlin/idea/kdoc/KDocRenderer.kt index ac5b9b11b70..59cf2a93ac8 100644 --- a/idea/src/org/jetbrains/kotlin/idea/kdoc/KDocRenderer.kt +++ b/idea/src/org/jetbrains/kotlin/idea/kdoc/KDocRenderer.kt @@ -29,8 +29,8 @@ import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag object KDocRenderer { fun renderKDoc(docComment: KDocTag): String { val content = docComment.getContent() - val result = StringBuilder("

") - result.append(markdownToHtml(content)) + val result = StringBuilder() + result.append(markdownToHtml(content, allowSingleParagraph = true)) if (docComment is KDocSection) { result.append("\n") val paramTags = docComment.findTagsByName("param").filter { it.getSubjectName() != null } @@ -47,7 +47,6 @@ object KDocRenderer { renderSeeAlso(docComment, result) } - result.append("

") return result.toString() } @@ -85,13 +84,13 @@ object KDocRenderer { } } - fun markdownToHtml(markdown: String): String { + fun markdownToHtml(markdown: String, allowSingleParagraph: Boolean = false): String { val markdownTree = MarkdownParser(CommonMarkMarkerProcessor.Factory).buildMarkdownTreeFromString(markdown) val markdownNode = MarkdownNode(markdownTree, null, markdown) // Avoid wrapping the entire converted contents in a

tag if it's just a single paragraph val maybeSingleParagraph = markdownNode.children.filter { it.type != MarkdownTokenTypes.EOL }.singleOrNull() - if (maybeSingleParagraph != null) { + if (maybeSingleParagraph != null && !allowSingleParagraph) { return maybeSingleParagraph.children.map { it.toHtml() }.join("") } else { return markdownNode.toHtml() @@ -120,7 +119,6 @@ object KDocRenderer { visit { node, processChildren -> fun wrapChildren(tag: String, newline: Boolean = false) { sb.append("<$tag>") - if (newline) sb.appendln() processChildren() sb.append("") if (newline) sb.appendln() @@ -142,13 +140,13 @@ object KDocRenderer { MarkdownElementTypes.ATX_6 -> wrapChildren("h6") MarkdownElementTypes.BLOCK_QUOTE -> wrapChildren("blockquote") MarkdownElementTypes.PARAGRAPH -> { - sb.trimTrailing() + sb.trimEnd() wrapChildren("p", newline = true) } MarkdownElementTypes.CODE_SPAN -> wrapChildren("code") MarkdownElementTypes.CODE_BLOCK, MarkdownElementTypes.CODE_FENCE -> { - sb.trimTrailing() + sb.trimEnd() sb.append("

")
                     processChildren()
                     sb.append("
")
@@ -168,7 +166,7 @@ object KDocRenderer {
                     val label = node.child(MarkdownElementTypes.LINK_TEXT)?.child(MarkdownTokenTypes.TEXT)?.text
                     val destination = node.child(MarkdownElementTypes.LINK_DESTINATION)?.text
                     if (label != null && destination != null) {
-                        sb.append("a href=\"${destination}\">${label.htmlEscape()}")
+                        sb.append("${label.htmlEscape()}")
                     }
                     else {
                         sb.append(node.text)
@@ -202,10 +200,10 @@ object KDocRenderer {
                 }
             }
         }
-        return sb.toString()
+        return sb.toString().trimEnd()
     }
 
-    fun StringBuilder.trimTrailing() {
+    fun StringBuilder.trimEnd() {
         while (length() > 0 && this[length() - 1] == ' ') {
             deleteCharAt(length() - 1)
         }
diff --git a/idea/testData/editor/quickDoc/KotlinClassUsedFromJava.java b/idea/testData/editor/quickDoc/KotlinClassUsedFromJava.java
index 0316a3cfa76..5b506f6ff27 100644
--- a/idea/testData/editor/quickDoc/KotlinClassUsedFromJava.java
+++ b/idea/testData/editor/quickDoc/KotlinClassUsedFromJava.java
@@ -6,5 +6,4 @@ class KotlinClassUsedFromJava {
     }
 }
 
-//INFO: internal final class Test defined in testing
Some comment
-//INFO: 

+//INFO: internal final class Test defined in testing
Some comment

diff --git a/idea/testData/editor/quickDoc/MethodFromStdLib.kt b/idea/testData/editor/quickDoc/MethodFromStdLib.kt
index 953f2f53dc8..8a922d47f55 100644
--- a/idea/testData/editor/quickDoc/MethodFromStdLib.kt
+++ b/idea/testData/editor/quickDoc/MethodFromStdLib.kt
@@ -2,5 +2,4 @@ fun test() {
     listOf(1, 2, 4).filter { it > 0 }
 }
 
-//INFO: inline public fun <T> Iterable<T>.filter(predicate: (T) → Boolean): List<T> defined in kotlin
Returns a list containing all elements matching the given predicate.
-//INFO: 

+//INFO: inline public fun <T> Iterable<T>.filter(predicate: (T) → Boolean): List<T> defined in kotlin
Returns a list containing all elements matching the given predicate.

diff --git a/idea/testData/editor/quickDoc/OnClassDeclarationWithNoPackage.kt b/idea/testData/editor/quickDoc/OnClassDeclarationWithNoPackage.kt
index dca8597b69b..f264773b65c 100644
--- a/idea/testData/editor/quickDoc/OnClassDeclarationWithNoPackage.kt
+++ b/idea/testData/editor/quickDoc/OnClassDeclarationWithNoPackage.kt
@@ -3,5 +3,4 @@
  */
 class Some
 
-//INFO: internal final class Some defined in root package
Usefull comment
-//INFO: 

+//INFO: internal final class Some defined in root package
Usefull comment

diff --git a/idea/testData/editor/quickDoc/OnFunctionDeclarationWithPackage.kt b/idea/testData/editor/quickDoc/OnFunctionDeclarationWithPackage.kt
index fb35b6666b6..208c243b211 100644
--- a/idea/testData/editor/quickDoc/OnFunctionDeclarationWithPackage.kt
+++ b/idea/testData/editor/quickDoc/OnFunctionDeclarationWithPackage.kt
@@ -12,6 +12,5 @@ package test
  */
 fun testFun(first: String, second: Int) = 12
 
-//INFO: internal fun testFun(first: String, second: Int): Int defined in test
Test function
+//INFO: internal fun testFun(first: String, second: Int): Int defined in test
Test function

 //INFO: 
Parameters:
first - Some
second - Other

-//INFO: 

diff --git a/idea/testData/editor/quickDoc/OnInheritedMethodUsage.kt b/idea/testData/editor/quickDoc/OnInheritedMethodUsage.kt
index 7a4a587d5ae..d31a6aed108 100644
--- a/idea/testData/editor/quickDoc/OnInheritedMethodUsage.kt
+++ b/idea/testData/editor/quickDoc/OnInheritedMethodUsage.kt
@@ -14,5 +14,4 @@ fun test() {
     D().foo()
 }
 
-//INFO: internal open fun foo(): Int defined in D
This method returns zero.
-//INFO: 

+//INFO: internal open fun foo(): Int defined in D
This method returns zero.

diff --git a/idea/testData/editor/quickDoc/OnInheritedPropertyUsage.kt b/idea/testData/editor/quickDoc/OnInheritedPropertyUsage.kt
index c9c19758f8c..be2a1d8a669 100644
--- a/idea/testData/editor/quickDoc/OnInheritedPropertyUsage.kt
+++ b/idea/testData/editor/quickDoc/OnInheritedPropertyUsage.kt
@@ -14,5 +14,4 @@ fun test() {
     D().foo
 }
 
-//INFO: internal open val foo: Int defined in D
This property returns zero.
-//INFO: 

+//INFO: internal open val foo: Int defined in D
This property returns zero.

diff --git a/idea/testData/editor/quickDoc/OnMethodUsage.kt b/idea/testData/editor/quickDoc/OnMethodUsage.kt
index f95cfe9e6f6..786c241ba16 100644
--- a/idea/testData/editor/quickDoc/OnMethodUsage.kt
+++ b/idea/testData/editor/quickDoc/OnMethodUsage.kt
@@ -12,6 +12,5 @@ fun test() {
     testMethod(1, "value")
 }
 
-//INFO: internal fun testMethod(a: Int, b: String): Unit defined in root package
Some documentation
+//INFO: internal fun testMethod(a: Int, b: String): Unit defined in root package
Some documentation

 //INFO: 
Parameters:
a - Some int
b - String

-//INFO: 

diff --git a/idea/testData/editor/quickDoc/OnMethodUsageMultiline.kt b/idea/testData/editor/quickDoc/OnMethodUsageMultiline.kt
index ca871fb8889..12ce680f394 100644
--- a/idea/testData/editor/quickDoc/OnMethodUsageMultiline.kt
+++ b/idea/testData/editor/quickDoc/OnMethodUsageMultiline.kt
@@ -10,5 +10,4 @@ fun test() {
     testMethod()
 }
 
-//INFO: internal fun testMethod(): Unit defined in root package
Some documentation on two lines.
-//INFO: 

+//INFO: internal fun testMethod(): Unit defined in root package
Some documentation on two lines.

diff --git a/idea/testData/editor/quickDoc/OnMethodUsageWithBracketsInParam.kt b/idea/testData/editor/quickDoc/OnMethodUsageWithBracketsInParam.kt
index 1b4b83ae749..b3b584e0eed 100644
--- a/idea/testData/editor/quickDoc/OnMethodUsageWithBracketsInParam.kt
+++ b/idea/testData/editor/quickDoc/OnMethodUsageWithBracketsInParam.kt
@@ -12,6 +12,5 @@ fun test() {
     testMethod(1, "value")
 }
 
-//INFO: internal fun testMethod(a: Int, b: String): Unit defined in root package
Some documentation
+//INFO: internal fun testMethod(a: Int, b: String): Unit defined in root package
Some documentation

 //INFO: 
Parameters:
a - Some int
b - String

-//INFO: 

diff --git a/idea/testData/editor/quickDoc/OnMethodUsageWithCodeBlock.kt b/idea/testData/editor/quickDoc/OnMethodUsageWithCodeBlock.kt
index 6a435c6507f..47ad5990e6e 100644
--- a/idea/testData/editor/quickDoc/OnMethodUsageWithCodeBlock.kt
+++ b/idea/testData/editor/quickDoc/OnMethodUsageWithCodeBlock.kt
@@ -17,10 +17,8 @@ fun test() {
     testMethod(1, "value")
 }
 
-//INFO: internal fun testMethod(): Unit defined in root package

-//INFO: Some documentation.

-//INFO:   

+//INFO: internal fun testMethod(): Unit defined in root package
Some documentation.

+//INFO: 

 //INFO: Code block
 //INFO: Second line
 //INFO: 
-//INFO: 

diff --git a/idea/testData/editor/quickDoc/OnMethodUsageWithMarkdown.kt b/idea/testData/editor/quickDoc/OnMethodUsageWithMarkdown.kt
index 7c54a82a753..c32fd5d1ebb 100644
--- a/idea/testData/editor/quickDoc/OnMethodUsageWithMarkdown.kt
+++ b/idea/testData/editor/quickDoc/OnMethodUsageWithMarkdown.kt
@@ -18,13 +18,7 @@ fun test() {
     testMethod(1, "value")
 }
 
-//INFO: internal fun testMethod(): Unit defined in root package

-//INFO: Some documentation. Bold underline code foo: bar (baz) quux  'apos'

-//INFO: 

-//INFO: a href="http://www.kotlinlang.org">Kotlin

-//INFO: 

-//INFO: C

-//INFO: 

-//INFO: See this class

-//INFO:
-//INFO: 

+//INFO: internal fun testMethod(): Unit defined in root package
Some documentation. Bold underline code foo: bar (baz) quux  'apos'

+//INFO: 
Kotlin

+//INFO: 
C

+//INFO: 
See this class

diff --git a/idea/testData/editor/quickDoc/OnMethodUsageWithReturnAndThrows.kt b/idea/testData/editor/quickDoc/OnMethodUsageWithReturnAndThrows.kt
index 5394c0b978a..df8929d1cef 100644
--- a/idea/testData/editor/quickDoc/OnMethodUsageWithReturnAndThrows.kt
+++ b/idea/testData/editor/quickDoc/OnMethodUsageWithReturnAndThrows.kt
@@ -14,8 +14,7 @@ fun test() {
     testMethod(1, "value")
 }
 
-//INFO: internal fun testMethod(a: Int, b: String): Unit defined in root package
Some documentation
+//INFO: internal fun testMethod(a: Int, b: String): Unit defined in root package
Some documentation

 //INFO: 
Parameters:
a - Some int
b - String

 //INFO: 
Returns:
Return value

 //INFO: 
Throws:
IllegalArgumentException - if the weather is bad

-//INFO: 

diff --git a/idea/testData/editor/quickDoc/OnMethodUsageWithSee.kt b/idea/testData/editor/quickDoc/OnMethodUsageWithSee.kt
index 28eebb459bf..263cb3f9bed 100644
--- a/idea/testData/editor/quickDoc/OnMethodUsageWithSee.kt
+++ b/idea/testData/editor/quickDoc/OnMethodUsageWithSee.kt
@@ -16,5 +16,5 @@ fun test() {
     testMethod(1, "value")
 }
 
-//INFO: internal fun testMethod(): Unit defined in root package

-//INFO: 
See Also:
C, D

+//INFO: internal fun testMethod(): Unit defined in root package

+//INFO: 
See Also:
C, D

diff --git a/idea/testData/editor/quickDoc/TopLevelMethodFromJava.java b/idea/testData/editor/quickDoc/TopLevelMethodFromJava.java
index cca09b295a3..88fb621eb85 100644
--- a/idea/testData/editor/quickDoc/TopLevelMethodFromJava.java
+++ b/idea/testData/editor/quickDoc/TopLevelMethodFromJava.java
@@ -8,5 +8,4 @@ class Testing {
     }
 }
 
-//INFO: internal fun foo(bar: Int): Unit defined in some
KDoc foo
-//INFO: 

+//INFO: internal fun foo(bar: Int): Unit defined in some
KDoc foo