From b237298c20fdf433b438eb52226e602f3111da28 Mon Sep 17 00:00:00 2001
From: Simon Ogorodnik <Simon.Ogorodnik@jetbrains.com>
Date: Tue, 10 Jul 2018 20:54:02 +0300
Subject: [PATCH] KT-22815: Position deprecated section between definition and
 description

---
 .../idea/KotlinQuickDocumentationProvider.kt  | 36 ++++++++++---------
 .../kotlin/idea/kdoc/KDocTemplate.kt          |  8 +++++
 2 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/idea/src/org/jetbrains/kotlin/idea/KotlinQuickDocumentationProvider.kt b/idea/src/org/jetbrains/kotlin/idea/KotlinQuickDocumentationProvider.kt
index 31cf0fe4116..b6f154db726 100644
--- a/idea/src/org/jetbrains/kotlin/idea/KotlinQuickDocumentationProvider.kt
+++ b/idea/src/org/jetbrains/kotlin/idea/KotlinQuickDocumentationProvider.kt
@@ -20,8 +20,7 @@ import com.google.common.html.HtmlEscapers
 import com.intellij.codeInsight.documentation.DocumentationManagerUtil
 import com.intellij.codeInsight.javadoc.JavaDocInfoGeneratorFactory
 import com.intellij.lang.documentation.AbstractDocumentationProvider
-import com.intellij.lang.documentation.DocumentationMarkup.DEFINITION_END
-import com.intellij.lang.documentation.DocumentationMarkup.DEFINITION_START
+import com.intellij.lang.documentation.DocumentationMarkup.*
 import com.intellij.lang.java.JavaDocumentationProvider
 import com.intellij.openapi.diagnostic.Logger
 import com.intellij.psi.PsiElement
@@ -346,8 +345,10 @@ class KotlinQuickDocumentationProvider : AbstractDocumentationProvider() {
             return KDocTemplate().apply {
                 definition {
                     renderDefinition(declarationDescriptor, DESCRIPTOR_RENDERER)
-                    renderDeprecationInfo(declarationDescriptor, deprecationProvider)
                 }
+
+                insertDeprecationInfo(declarationDescriptor, deprecationProvider)
+
                 if (!quickNavigation) {
                     description {
                         val comment = declarationDescriptor.findKDoc { DescriptorToSourceUtilsIde.getAnyDeclaration(ktElement.project, it) }
@@ -420,25 +421,26 @@ class KotlinQuickDocumentationProvider : AbstractDocumentationProvider() {
             return ""
         }
 
-        private fun StringBuilder.renderDeprecationInfo(
+        private fun KDocTemplate.insertDeprecationInfo(
             declarationDescriptor: DeclarationDescriptor,
             deprecationResolver: DeprecationResolver
         ) {
-            val deprecation = deprecationResolver.getDeprecations(declarationDescriptor).firstOrNull() ?: return
+            val deprecationInfo = deprecationResolver.getDeprecations(declarationDescriptor).firstOrNull() ?: return
 
-
-            wrapTag("DL") {
-                deprecation.message?.let { message ->
-                    wrapTag("DT") { wrapTag("b") { append("Deprecated:") } }
-                    wrapTag("DD") {
-                        append(message.htmlEscape())
-                    }
+            deprecation {
+                deprecationInfo.message?.let { message ->
+                    append(SECTION_HEADER_START)
+                    append("Deprecated:")
+                    append(SECTION_SEPARATOR)
+                    append(message.htmlEscape())
+                    append(SECTION_END)
                 }
-                deprecation.deprecatedByAnnotationReplaceWithExpression()?.let { replaceWith ->
-                    wrapTag("DT") { wrapTag("b") { append("Replace with:") } }
-                    wrapTag("DD") {
-                        wrapTag("code") { append(replaceWith.htmlEscape()) }
-                    }
+                deprecationInfo.deprecatedByAnnotationReplaceWithExpression()?.let { replaceWith ->
+                    append(SECTION_HEADER_START)
+                    append("Replace with:")
+                    append(SECTION_SEPARATOR)
+                    wrapTag("code") { append(replaceWith.htmlEscape()) }
+                    append(SECTION_END)
                 }
             }
         }
diff --git a/idea/src/org/jetbrains/kotlin/idea/kdoc/KDocTemplate.kt b/idea/src/org/jetbrains/kotlin/idea/kdoc/KDocTemplate.kt
index be029e652d8..7e8be78cde3 100644
--- a/idea/src/org/jetbrains/kotlin/idea/kdoc/KDocTemplate.kt
+++ b/idea/src/org/jetbrains/kotlin/idea/kdoc/KDocTemplate.kt
@@ -12,11 +12,19 @@ open class KDocTemplate : Template<StringBuilder> {
 
     val description = Placeholder<StringBuilder>()
 
+    val deprecation = Placeholder<StringBuilder>()
+
     override fun StringBuilder.apply() {
         append(DEFINITION_START)
         insert(definition)
         append(DEFINITION_END)
 
+        if (!deprecation.isEmpty()) {
+            append(SECTIONS_START)
+            insert(deprecation)
+            append(SECTIONS_END)
+        }
+
         insert(description)
     }