From fdfb843fdcfa8435507abd927b340f6eec87fd9b Mon Sep 17 00:00:00 2001
From: Dmitry Jemerov <yole@jetbrains.com>
Date: Fri, 6 Feb 2015 16:58:36 +0100
Subject: [PATCH] add @sample known tag; handle @constructor tag in findKDoc()

---
 .../org/jetbrains/kotlin/kdoc/KDocFinder.kt   |  9 ++++++++
 .../kotlin/kdoc/parser/KDocKnownTag.java      |  3 ++-
 .../kdoc/psi/api/{KDoc.java => KDoc.kt}       | 21 +++++++++----------
 .../kotlin/kdoc/psi/impl/KDocImpl.kt          |  8 +++++++
 4 files changed, 29 insertions(+), 12 deletions(-)
 rename compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/api/{KDoc.java => KDoc.kt} (58%)

diff --git a/compiler/frontend/src/org/jetbrains/kotlin/kdoc/KDocFinder.kt b/compiler/frontend/src/org/jetbrains/kotlin/kdoc/KDocFinder.kt
index aa688f1aa4a..7ee2e08d951 100644
--- a/compiler/frontend/src/org/jetbrains/kotlin/kdoc/KDocFinder.kt
+++ b/compiler/frontend/src/org/jetbrains/kotlin/kdoc/KDocFinder.kt
@@ -22,6 +22,8 @@ import org.jetbrains.kotlin.resolve.source.PsiSourceElement
 import org.jetbrains.kotlin.psi.JetDeclaration
 import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
 import org.jetbrains.kotlin.descriptors.CallableDescriptor
+import org.jetbrains.kotlin.descriptors.ConstructorDescriptor
+import org.jetbrains.kotlin.kdoc.parser.KDocKnownTag
 
 fun findKDoc(declaration: DeclarationDescriptor): KDocTag? {
     if (declaration is DeclarationDescriptorWithSource) {
@@ -29,6 +31,13 @@ fun findKDoc(declaration: DeclarationDescriptor): KDocTag? {
         if (psiDeclaration is JetDeclaration) {
             val kdoc = psiDeclaration.getDocComment()
             if (kdoc != null) {
+                if (declaration is ConstructorDescriptor) {
+                    // ConstructorDescriptor resolves to the same JetDeclaration
+                    val constructorSection = kdoc.findSectionByTag(KDocKnownTag.CONSTRUCTOR)
+                    if (constructorSection != null) {
+                        return constructorSection
+                    }
+                }
                 return kdoc.getDefaultSection()
             }
         }
diff --git a/compiler/frontend/src/org/jetbrains/kotlin/kdoc/parser/KDocKnownTag.java b/compiler/frontend/src/org/jetbrains/kotlin/kdoc/parser/KDocKnownTag.java
index 5437b3a912f..ffc2ff7e5e0 100644
--- a/compiler/frontend/src/org/jetbrains/kotlin/kdoc/parser/KDocKnownTag.java
+++ b/compiler/frontend/src/org/jetbrains/kotlin/kdoc/parser/KDocKnownTag.java
@@ -27,7 +27,8 @@ public enum KDocKnownTag {
     SEE(true, false),
     SINCE(false, false),
     CONSTRUCTOR(false, true),
-    PROPERTY(true, true);
+    PROPERTY(true, true),
+    SAMPLE(true, false);
 
     private final boolean takesReference;
     private final boolean startsSection;
diff --git a/compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/api/KDoc.java b/compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/api/KDoc.kt
similarity index 58%
rename from compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/api/KDoc.java
rename to compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/api/KDoc.kt
index 79a1bfa3139..20e36fb5ef4 100644
--- a/compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/api/KDoc.java
+++ b/compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/api/KDoc.kt
@@ -14,18 +14,17 @@
  * limitations under the License.
  */
 
-package org.jetbrains.kotlin.kdoc.psi.api;
+package org.jetbrains.kotlin.kdoc.psi.api
 
-import com.intellij.psi.PsiComment;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import org.jetbrains.kotlin.kdoc.psi.impl.KDocSection;
-import org.jetbrains.kotlin.psi.JetDeclaration;
+import com.intellij.psi.PsiComment
+import org.jetbrains.kotlin.kdoc.psi.impl.KDocSection
+import org.jetbrains.kotlin.psi.JetDeclaration
+import org.jetbrains.kotlin.kdoc.parser.KDocKnownTag
 
 // Don't implement JetElement (or it will be treated as statement)
-public interface KDoc extends PsiComment {
-    @Nullable
-    JetDeclaration getOwner();
-    @NotNull
-    KDocSection getDefaultSection();
+public trait KDoc : PsiComment {
+    public fun getOwner(): JetDeclaration?
+    public fun getDefaultSection(): KDocSection
+    public fun findSectionByName(name: String): KDocSection?
+    public fun findSectionByTag(tag: KDocKnownTag): KDocSection?
 }
diff --git a/compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocImpl.kt b/compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocImpl.kt
index 1d3e93226fb..e0adf734e73 100644
--- a/compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocImpl.kt
+++ b/compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocImpl.kt
@@ -26,6 +26,8 @@ import org.jetbrains.kotlin.lexer.JetTokens
 import org.jetbrains.kotlin.psi.JetDeclaration
 import org.jetbrains.kotlin.psi.psiUtil.getParentOfType
 import org.jetbrains.kotlin.psi.psiUtil.getChildOfType
+import org.jetbrains.kotlin.psi.psiUtil.getChildrenOfType
+import org.jetbrains.kotlin.kdoc.parser.KDocKnownTag
 
 public class KDocImpl(buffer: CharSequence?) : LazyParseablePsiElement(KDocTokens.KDOC, buffer), KDoc {
 
@@ -38,4 +40,10 @@ public class KDocImpl(buffer: CharSequence?) : LazyParseablePsiElement(KDocToken
     override fun getOwner(): JetDeclaration? = getParentOfType<JetDeclaration>(true)
 
     override fun getDefaultSection(): KDocSection = getChildOfType<KDocSection>()!!
+
+    override fun findSectionByName(name: String): KDocSection? =
+        getChildrenOfType<KDocSection>().firstOrNull { it.getName() == name }
+
+    override fun findSectionByTag(tag: KDocKnownTag): KDocSection? =
+        findSectionByName(tag.name().toLowerCase())
 }