azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
structured rendering of doc comments in quick documentation dialog
This commit is contained in:
Dmitry Jemerov
2015-01-21 23:32:10 +01:00
parent 4f2ecffee1 906c0fd7f7
commit f4a25f69b1
12 changed files with 244 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
compiler/frontend/src/org/jetbrains/kotlin/kdoc/parser/KDocKnownTag.java
+6 -5
View File
@@ -45,11 +45,12 @@ public enum KDocKnownTag {
public static KDocKnownTag findByTagName(String tagName) {
if (tagName.startsWith("@")) {
try {
return valueOf(tagName.substring(1).toUpperCase());
}
catch (IllegalArgumentException ignored) {
}
tagName = tagName.substring(1);
}
try {
return valueOf(tagName.toUpperCase());
}
catch (IllegalArgumentException ignored) {
}
return null;
}
compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocLink.java → compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocLink.kt
+9 -6
View File
@@ -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 org.jetbrains.annotations.NotNull;
import com.intellij.lang.ASTNode
public class KDocLink extends KDocElementImpl {
public KDocLink(@NotNull ASTNode node) {
super(node);
public class KDocLink(node: ASTNode) : KDocElementImpl(node) {
fun getLinkText(): String {
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.java → compiler/frontend/src/org/jetbrains/kotlin/kdoc/psi/impl/KDocSection.kt
+13 -6
View File
@@ -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 org.jetbrains.annotations.NotNull;
import com.intellij.lang.ASTNode
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 KDocSection(@NotNull ASTNode node) {
super(node);
public class KDocSection(node: ASTNode) : KDocTag(node) {
public fun findTagsByName(name: String): List<KDocTag> {
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
-84
View File
@@ -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
+98
View File
@@ -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
+1 -12
View File
@@ -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
+66
View File
@@ -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
+3 -3
View File
@@ -7,9 +7,9 @@ package test
* Test function
*
* @param first - Some
* @param second - Other
* @param first Some
* @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
+3 -3
View File
@@ -1,8 +1,8 @@
/**
Some documentation
@param a - Some int
* @param b: String
* @param a Some int
* @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
+15
View File
@@ -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
+17
View File
@@ -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
+13
View File
@@ -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");