Merge pull request #552 from JetBrains/rr/yole/kdoc-generate

structured rendering of doc comments in quick documentation dialog

compiler/frontend/src/org/jetbrains/kotlin/kdoc/parser/KDocKnownTag.java

@@ -45,11 +45,12 @@ public enum KDocKnownTag {
 
     public static KDocKnownTag findByTagName(String tagName) {
         if (tagName.startsWith("@")) {
-            try {
+            tagName = tagName.substring(1);
-                return valueOf(tagName.substring(1).toUpperCase());
+        }
-            }
+        try {
-            catch (IllegalArgumentException ignored) {
+            return valueOf(tagName.toUpperCase());
-            }
+        }
+        catch (IllegalArgumentException ignored) {
         }
         return null;
     }

compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocLink.kt

@@ -14,13 +14,16 @@
  * limitations under the License.
  */
 
-package org.jetbrains.kotlin.kdoc.psi.impl;
+package org.jetbrains.kotlin.kdoc.psi.impl
 
-import com.intellij.lang.ASTNode;
+import com.intellij.lang.ASTNode
-import org.jetbrains.annotations.NotNull;
 
-public class KDocLink extends KDocElementImpl {
+public class KDocLink(node: ASTNode) : KDocElementImpl(node) {
-    public KDocLink(@NotNull ASTNode node) {
+    fun getLinkText(): String {
-        super(node);
+        val text = getText()
+        if (text.startsWith('[') && text.endsWith(']')) {
+            return text.substring(1, text.length() - 1)
+        }
+        return text
     }
 }

compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocSection.kt

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-package org.jetbrains.kotlin.kdoc.psi.impl;
+package org.jetbrains.kotlin.kdoc.psi.impl
 
-import com.intellij.lang.ASTNode;
+import com.intellij.lang.ASTNode
-import org.jetbrains.annotations.NotNull;
+import com.intellij.psi.util.PsiTreeUtil
 
 /**
  * The part of a doc comment which describes a single class, method or property
@@ -25,8 +25,15 @@ import org.jetbrains.annotations.NotNull;
  * can have sections for the class itself, its primary constructor and each of the
  * properties defined in the primary constructor.
  */
-public class KDocSection extends KDocTag {
+public class KDocSection(node: ASTNode) : KDocTag(node) {
-    public KDocSection(@NotNull ASTNode node) {
+    public fun findTagsByName(name: String): List<KDocTag> {
-        super(node);
+        val tags = PsiTreeUtil.getChildrenOfType<KDocTag>(this, javaClass<KDocTag>())
+        if (tags == null) {
+            return listOf()
+        }
+        return tags.filter { it.getName() == name }
     }
+
+    public fun findTagByName(name: String): KDocTag?
+        = findTagsByName(name).firstOrNull()
 }

compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocTag.java

@@ -1,84 +0,0 @@
-/*
- * Copyright 2010-2015 JetBrains s.r.o.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package org.jetbrains.kotlin.kdoc.psi.impl;
-
-import com.intellij.lang.ASTNode;
-import com.intellij.openapi.util.text.StringUtil;
-import com.intellij.psi.TokenType;
-import com.intellij.psi.tree.IElementType;
-import com.intellij.psi.util.PsiTreeUtil;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.kotlin.kdoc.lexer.KDocTokens;
-import org.jetbrains.kotlin.kdoc.parser.KDocElementTypes;
-
-public class KDocTag extends KDocElementImpl {
-    public KDocTag(@NotNull ASTNode node) {
-        super(node);
-    }
-
-    public String getContent() {
-        StringBuilder builder = new StringBuilder();
-
-        boolean contentStarted = false;
-        boolean afterAsterisk = false;
-        boolean startsWithTagName = false;
-
-        ASTNode[] children = getNode().getChildren(null);
-        for (int i = 0; i < children.length; i++) {
-            ASTNode node = children[i];
-            IElementType type = node.getElementType();
-            if (i == 0 && type == KDocTokens.TAG_NAME) {
-                startsWithTagName = true;
-            }
-            if (KDocTokens.CONTENT_TOKENS.contains(type) || type == KDocElementTypes.KDOC_LINK) {
-                contentStarted = true;
-                builder.append(afterAsterisk ? StringUtil.trimLeading(node.getText()) : node.getText());
-                afterAsterisk = false;
-            }
-
-            if (type == KDocTokens.LEADING_ASTERISK) {
-                afterAsterisk = true;
-            }
-
-            if (type == TokenType.WHITE_SPACE) {
-                if (i == 1 && startsWithTagName) {
-                    builder.append(node.getText());
-                }
-                else if (contentStarted) {
-                    builder.append(StringUtil.repeat("\n", StringUtil.countNewLines(node.getText())));
-                }
-            }
-
-            if (type == KDocElementTypes.KDOC_TAG) {
-                break;
-            }
-        }
-
-        return builder.toString();
-    }
-
-    public String getContentWithTags() {
-        StringBuilder content = new StringBuilder(getContent());
-        KDocTag[] subTags = PsiTreeUtil.getChildrenOfType(this, KDocTag.class);
-        if (subTags != null) {
-            for (KDocTag tag : subTags) {
-                content.append(tag.getContentWithTags()).append("\n");
-            }
-        }
-        return content.toString();
-    }
-}

compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocTag.kt

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2010-2015 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.jetbrains.kotlin.kdoc.psi.impl
+
+import com.intellij.lang.ASTNode
+import com.intellij.openapi.util.text.StringUtil
+import com.intellij.psi.TokenType
+import org.jetbrains.kotlin.kdoc.lexer.KDocTokens
+import org.jetbrains.kotlin.kdoc.parser.KDocElementTypes
+import org.jetbrains.kotlin.kdoc.parser.KDocKnownTag
+
+public open class KDocTag(node: ASTNode) : KDocElementImpl(node) {
+
+    /**
+     * Returns the name of this tag, not including the leading @ character.
+     *
+     * @return tag name or null if this tag represents the default section of a doc comment
+     * or the code has a syntax error.
+     */
+    override fun getName(): String? {
+        val tagName = findChildByType(KDocTokens.TAG_NAME)
+        if (tagName != null) {
+            return tagName.getText().substring(1)
+        }
+        return null
+    }
+
+    /**
+     * Returns the name of the entity documented by this tag (for example, the name of the parameter
+     * for the @param tag), or null if this tag does not document any specific entity.
+     */
+    public fun getSubjectName(): String? {
+        val children = childrenAfterTagName()
+        if (hasSubject(children)) {
+            return (children.firstOrNull()?.getPsi() as? KDocLink)?.getLinkText()
+        }
+        return null
+    }
+
+    private fun hasSubject(contentChildren: List<ASTNode>): Boolean {
+        val name = getName()
+        val knownTag = if (name != null) KDocKnownTag.findByTagName(name) else null
+        if (knownTag?.isReferenceRequired() ?: false) {
+            return contentChildren.firstOrNull()?.getElementType() == KDocElementTypes.KDOC_LINK;
+        }
+        return false
+    }
+
+    private fun childrenAfterTagName(): List<ASTNode> =
+        getNode().getChildren(null)
+                .dropWhile { it.getElementType() == KDocTokens.TAG_NAME }
+                .dropWhile { it.getElementType() == TokenType.WHITE_SPACE }
+
+    public fun getContent(): String {
+        val builder = StringBuilder()
+
+        var contentStarted = false
+        var afterAsterisk = false
+
+        var children = childrenAfterTagName()
+        if (hasSubject(children)) {
+            children = children.drop(1)
+        }
+        for (node in children) {
+            val type = node.getElementType()
+            if (KDocTokens.CONTENT_TOKENS.contains(type) || type == KDocElementTypes.KDOC_LINK) {
+                contentStarted = true
+                builder.append(if (afterAsterisk) StringUtil.trimLeading(node.getText()) else node.getText())
+                afterAsterisk = false
+            }
+            if (type == KDocTokens.LEADING_ASTERISK) {
+                afterAsterisk = true
+            }
+            if (type == TokenType.WHITE_SPACE && contentStarted) {
+                builder.append(StringUtil.repeat("\n", StringUtil.countNewLines(node.getText())))
+            }
+            if (type == KDocElementTypes.KDOC_TAG) {
+                break
+            }
+        }
+
+        return builder.toString()
+    }
+}

idea/src/org/jetbrains/kotlin/idea/JetQuickDocumentationProvider.java

@@ -19,7 +19,6 @@ package org.jetbrains.kotlin.idea;
 import com.google.common.base.Predicate;
 import com.intellij.lang.documentation.AbstractDocumentationProvider;
 import com.intellij.lang.java.JavaDocumentationProvider;
-import com.intellij.openapi.util.text.StringUtil;
 import com.intellij.psi.PsiElement;
 import com.intellij.psi.PsiWhiteSpace;
 import com.intellij.psi.util.PsiTreeUtil;
@@ -93,7 +92,7 @@ public class JetQuickDocumentationProvider extends AbstractDocumentationProvider
 
         KDocTag comment = KdocPackage.findKDoc(declarationDescriptor);
         if (comment != null) {
-            renderedDecl = renderedDecl + "<br/>" + kDocToHtml(comment);
+            renderedDecl = renderedDecl + "<br/>" + org.jetbrains.kotlin.idea.kdoc.KdocPackage.renderKDoc(comment);
         }
 
         return renderedDecl;
@@ -111,14 +110,4 @@ public class JetQuickDocumentationProvider extends AbstractDocumentationProvider
 
         return null;
     }
-
-    private static String kDocToHtml(@NotNull KDocTag comment) {
-        // TODO: Parse and show markdown comments as html
-        String content = comment.getContentWithTags();
-        String htmlContent = StringUtil.replace(content, "\n", "<br/>")
-                .replaceAll("(@param)\\s+(\\w+)", "@param - <i>$2</i>")
-                .replaceAll("(@\\w+)", "<b>$1</b>");
-
-        return "<p>" + htmlContent + "</p>";
-    }
 }

idea/src/org/jetbrains/kotlin/idea/kdoc/KDocRenderer.kt

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2010-2015 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.jetbrains.kotlin.idea.kdoc
+
+import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
+import com.intellij.openapi.util.text.StringUtil
+import org.jetbrains.kotlin.kdoc.psi.impl.KDocSection
+
+fun renderKDoc(docComment: KDocTag): String {
+    val content = docComment.getContent()
+    val result = StringBuilder("<p>")
+    result.append(markdownToHtml(content))
+    if (docComment is KDocSection) {
+        val paramTags = docComment.findTagsByName("param").filter { it.getSubjectName() != null }
+        renderTagList(paramTags, "Parameters", result)
+
+        renderTag(docComment.findTagByName("return"), "Returns", result)
+
+        val throwsTags = (docComment.findTagsByName("exception").union(docComment.findTagsByName("throws")))
+                .filter { it.getSubjectName() != null }
+        renderTagList(throwsTags, "Throws", result)
+
+        renderTag(docComment.findTagByName("author"), "Author", result)
+        renderTag(docComment.findTagByName("since"), "Since", result)
+    }
+    result.append("</p>")
+    return result.toString()
+}
+
+private fun renderTagList(tags: List<KDocTag>, title: String, to: StringBuilder) {
+    if (tags.isEmpty()) {
+        return
+    }
+    to.append("<dl><dt><b>${title}:</b></dt>")
+    tags.forEach {
+        to.append("<dd><code>${it.getSubjectName()}</code> - ${markdownToHtml(it.getContent().trimLeading())}</dd>")
+    }
+    to.append("</dl>")
+}
+
+private fun renderTag(tag: KDocTag?, title: String, to: StringBuilder) {
+    if (tag != null) {
+        to.append("<dl><dt><b>${title}:</b></dt>")
+        to.append("<dd>${markdownToHtml(tag.getContent())}</dd>")
+        to.append("</dl>")
+    }
+}
+
+fun markdownToHtml(markdown: String): String {
+    // TODO Integrate a real Markdown parser
+    return StringUtil.replace(markdown, "\n", "<br/>");
+}

idea/testData/editor/quickDoc/OnFunctionDeclarationWithPackage.kt

@@ -7,9 +7,9 @@ package test
  * Test function
 
  *
- * @param first - Some
+ * @param first Some
- * @param second - Other
+ * @param second Other
  */
 fun <caret>testFun(first: String, second: Int) = 12
 
-// INFO: <b>internal</b> <b>fun</b> testFun(first: String, second: Int): Int<br/><p>Test function<br/><br/><br/><b>@param</b> - <i>first</i> - Some<br/><b>@param</b> - <i>second</i> - Other<br/></p>
+// INFO: <b>internal</b> <b>fun</b> testFun(first: String, second: Int): Int<br/><p>Test function<br/><br/><br/><dl><dt><b>Parameters:</b></dt><dd><code>first</code> - Some</dd><dd><code>second</code> - Other</dd></dl></p>

idea/testData/editor/quickDoc/OnMethodUsage.kt

@@ -1,8 +1,8 @@
 /**
  Some documentation
 
- @param a - Some int
+ * @param a Some int
- * @param b: String
+ * @param b String
  */
 fun testMethod(a: Int, b: String) {
 
@@ -12,4 +12,4 @@ fun test() {
     <caret>testMethod(1, "value")
 }
 
-// INFO: <b>internal</b> <b>fun</b> testMethod(a: Int, b: String): Unit<br/><p>Some documentation<br/><br/><b>@param</b> - <i>a</i> - Some int<br/><b>@param</b> - <i>b</i>: String<br/></p>
+// INFO: <b>internal</b> <b>fun</b> testMethod(a: Int, b: String): Unit<br/><p>Some documentation<br/><br/><dl><dt><b>Parameters:</b></dt><dd><code>a</code> - Some int</dd><dd><code>b</code> - String</dd></dl></p>

idea/testData/editor/quickDoc/OnMethodUsageWithBracketsInParam.kt

@@ -0,0 +1,15 @@
+/**
+ Some documentation
+
+ * @param[a] Some int
+ * @param[b] String
+ */
+fun testMethod(a: Int, b: String) {
+
+}
+
+fun test() {
+    <caret>testMethod(1, "value")
+}
+
+// INFO: <b>internal</b> <b>fun</b> testMethod(a: Int, b: String): Unit<br/><p>Some documentation<br/><br/><dl><dt><b>Parameters:</b></dt><dd><code>a</code> - Some int</dd><dd><code>b</code> - String</dd></dl></p>

idea/testData/editor/quickDoc/OnMethodUsageWithReturnAndThrows.kt

@@ -0,0 +1,17 @@
+/**
+Some documentation
+
+ * @param a Some int
+ * @param b String
+ * @return Return value
+ * @throws IllegalArgumentException if the weather is bad
+ */
+fun testMethod(a: Int, b: String) {
+
+}
+
+fun test() {
+    <caret>testMethod(1, "value")
+}
+
+// INFO: <b>internal</b> <b>fun</b> testMethod(a: Int, b: String): Unit<br/><p>Some documentation<br/><br/><dl><dt><b>Parameters:</b></dt><dd><code>a</code> - Some int</dd><dd><code>b</code> - String</dd></dl><dl><dt><b>Returns:</b></dt><dd> value</dd></dl><dl><dt><b>Throws:</b></dt><dd><code>IllegalArgumentException</code> - if the weather is bad</dd></dl></p>

idea/tests/org/jetbrains/kotlin/idea/editor/quickDoc/JetQuickDocProviderTestGenerated.java

@@ -17,6 +17,7 @@
 package org.jetbrains.kotlin.idea.editor.quickDoc;
 
 import com.intellij.testFramework.TestDataPath;
+import org.jetbrains.kotlin.test.InnerTestClasses;
 import org.jetbrains.kotlin.test.JUnit3RunnerWithInners;
 import org.jetbrains.kotlin.test.JetTestUtils;
 import org.jetbrains.kotlin.test.TestMetadata;
@@ -107,6 +108,18 @@ public class JetQuickDocProviderTestGenerated extends AbstractJetQuickDocProvide
         doTest(fileName);
     }
 
+    @TestMetadata("OnMethodUsageWithBracketsInParam.kt")
+    public void testOnMethodUsageWithBracketsInParam() throws Exception {
+        String fileName = JetTestUtils.navigationMetadata("idea/testData/editor/quickDoc/OnMethodUsageWithBracketsInParam.kt");
+        doTest(fileName);
+    }
+
+    @TestMetadata("OnMethodUsageWithReturnAndThrows.kt")
+    public void testOnMethodUsageWithReturnAndThrows() throws Exception {
+        String fileName = JetTestUtils.navigationMetadata("idea/testData/editor/quickDoc/OnMethodUsageWithReturnAndThrows.kt");
+        doTest(fileName);
+    }
+
     @TestMetadata("TopLevelMethodFromJava.java")
     public void testTopLevelMethodFromJava() throws Exception {
         String fileName = JetTestUtils.navigationMetadata("idea/testData/editor/quickDoc/TopLevelMethodFromJava.java");