add @sample known tag; handle @constructor tag in findKDoc()

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()
             }
         }

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;

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?
 }

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())
 }