Merge branch 'rr/yole/j2k-convert-javadoc'

2015-03-04 17:14:52 +01:00
parent 3aa5f5200b 9372339567
commit 155ce4221c
21 changed files with 486 additions and 12 deletions
@@ -16,10 +16,12 @@

 package org.jetbrains.kotlin.j2k

+import com.intellij.codeInsight.NullableNotNullManager
+import com.intellij.openapi.util.text.StringUtil
 import com.intellij.psi.*
+import com.intellij.psi.javadoc.PsiDocTag
 import org.jetbrains.kotlin.j2k.ast.*
 import org.jetbrains.kotlin.j2k.ast.Annotation
-import com.intellij.codeInsight.NullableNotNullManager

 class AnnotationConverter(private val converter: Converter) {
    public val annotationsToRemove: Set<String> = (NullableNotNullManager.getInstance(converter.project).getNotNulls()
@@ -32,10 +34,9 @@ class AnnotationConverter(private val converter: Converter) {
    private fun convertAnnotationsOnly(owner: PsiModifierListOwner): Annotations {
        val modifierList = owner.getModifierList()
        val annotations = modifierList?.getAnnotations()?.filter { it.getQualifiedName() !in annotationsToRemove }
-        if (annotations == null || annotations.isEmpty()) return Annotations.Empty

-        val newLines = run {
-            if (!modifierList!!.isInSingleLine()) {
+        var convertedAnnotations: List<Annotation> = if (annotations != null && annotations.isNotEmpty()) {
+            val newLines = if (!modifierList!!.isInSingleLine()) {
                true
            }
            else {
@@ -46,10 +47,31 @@ class AnnotationConverter(private val converter: Converter) {
                }
                if (child is PsiWhiteSpace) !child!!.isInSingleLine() else false
            }
+
+            annotations.map { convertAnnotation(it, owner is PsiLocalVariable, newLines) }.filterNotNull() //TODO: brackets are also needed for local classes
+        }
+        else {
+            listOf()
        }

-        val list = annotations.map { convertAnnotation(it, owner is PsiLocalVariable, newLines) }.filterNotNull() //TODO: brackets are also needed for local classes
-        return Annotations(list).assignNoPrototype()
+        if (owner is PsiDocCommentOwner) {
+            val deprecatedAnnotation = convertDeprecatedJavadocTag(owner)
+            if (deprecatedAnnotation != null) {
+                convertedAnnotations += deprecatedAnnotation
+            }
+        }
+
+        return Annotations(convertedAnnotations).assignNoPrototype()
+    }
+
+    private fun convertDeprecatedJavadocTag(element: PsiDocCommentOwner): Annotation? {
+        val deprecatedTag = element.getDocComment()?.findTagByName("deprecated") ?: return null
+        val deferredExpression = converter.deferredElement<Expression> {
+            LiteralExpression("\"" + StringUtil.escapeStringCharacters(deprecatedTag.content()) + "\"").assignNoPrototype()
+        }
+        return Annotation(Identifier("deprecated").assignPrototype(deprecatedTag.getNameElement()),
+                          listOf(null to deferredExpression), false, true)
+                .assignPrototype(deprecatedTag)
    }

    private fun convertModifiersToAnnotations(owner: PsiModifierListOwner): Annotations {
@@ -16,14 +16,15 @@

 package org.jetbrains.kotlin.j2k

+import com.intellij.openapi.util.text.StringUtil
 import com.intellij.psi.*
-import java.util.HashSet
+import com.intellij.psi.javadoc.PsiDocComment
+import org.jetbrains.kotlin.j2k.ast.CommentsAndSpacesInheritance
+import org.jetbrains.kotlin.j2k.ast.Element
 import org.jetbrains.kotlin.psi.psiUtil.isAncestor
 import java.util.ArrayList
-import org.jetbrains.kotlin.j2k.ast.Element
+import java.util.HashSet
 import kotlin.platform.platformName
-import org.jetbrains.kotlin.j2k.ast.CommentsAndSpacesInheritance
-import com.intellij.openapi.util.text.StringUtil

 fun<T> CodeBuilder.append(generators: Collection<() -> T>, separator: String, prefix: String = "", suffix: String = ""): CodeBuilder {
    if (generators.isNotEmpty()) {
@@ -57,8 +58,14 @@ class CodeBuilder(private val topElement: PsiElement?) {
    public fun append(text: String): CodeBuilder
            = append(text, false)

-    private fun appendCommentOrWhiteSpace(element: PsiElement)
-            = append(element.getText()!!, element.isEndOfLineComment())
+    private fun appendCommentOrWhiteSpace(element: PsiElement) {
+        if (element is PsiDocComment) {
+            append(DocCommentConverter.convertDocComment(element), false)
+        }
+        else {
+            append(element.getText()!!, element.isEndOfLineComment())
+        }
+    }

    private fun append(text: String, endOfLineComment: Boolean = false): CodeBuilder {
        if (text.isEmpty()) {
@@ -0,0 +1,220 @@
+/*
+ * 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.j2k
+
+import com.intellij.ide.highlighter.HtmlFileType
+import com.intellij.openapi.util.text.StringUtil
+import com.intellij.psi.*
+import com.intellij.psi.javadoc.PsiDocComment
+import com.intellij.psi.javadoc.PsiDocTag
+import com.intellij.psi.javadoc.PsiDocToken
+import com.intellij.psi.javadoc.PsiInlineDocTag
+import com.intellij.psi.xml.XmlFile
+import com.intellij.psi.xml.XmlTag
+import com.intellij.psi.xml.XmlText
+import com.intellij.psi.xml.XmlTokenType
+import java.util.Stack
+
+object DocCommentConverter {
+    fun convertDocComment(docComment: PsiDocComment): String {
+        val html = StringBuilder {
+            appendJavadocElements(docComment.getDescriptionElements())
+
+            for (tag in docComment.getTags()) {
+                when (tag.getName()) {
+                    "deprecated" -> continue
+                    "see" -> append("@see ${convertJavadocLink(tag.content())}\n")
+                    else -> appendJavadocElements(tag.getChildren()).append("\n")
+                }
+            }
+        }.toString()
+
+        if (html.trim().isEmpty() && docComment.findTagByName("deprecated") != null) {
+            // @deprecated was the only content of the doc comment; we can drop the comment
+            return ""
+        }
+
+        val htmlFile = PsiFileFactory.getInstance(docComment.getProject()).createFileFromText(
+                "javadoc.html", HtmlFileType.INSTANCE, html)
+        val htmlToMarkdownConverter = HtmlToMarkdownConverter()
+        htmlFile.accept(htmlToMarkdownConverter)
+        return htmlToMarkdownConverter.result
+    }
+
+    private fun StringBuilder.appendJavadocElements(elements: Array<PsiElement>): StringBuilder {
+        elements.forEach {
+            if (it is PsiInlineDocTag) {
+                append(convertInlineDocTag(it))
+            }
+            else {
+                append(it.getText())
+            }
+        }
+        return this
+    }
+
+    private fun convertInlineDocTag(tag: PsiInlineDocTag) = when(tag.getName()) {
+        "code", "literal" -> {
+            val text = tag.getDataElements().map { it.getText() }.join()
+            val escaped = StringUtil.escapeXml(text.trimLeading())
+            if (tag.getName() == "code") "<code>$escaped</code>" else escaped
+        }
+
+        "link", "linkplain" -> {
+            val valueElement = tag.linkElement()
+            val labelText = tag.getDataElements().firstOrNull { it is PsiDocToken }?.getText() ?: ""
+            val kdocLink = convertJavadocLink(valueElement?.getText())
+            val linkText = if (labelText.isEmpty()) kdocLink else StringUtil.escapeXml(labelText)
+            "<a docref=\"$kdocLink\">$linkText</a>"
+        }
+
+        else -> tag.getText()
+    }
+
+    private fun convertJavadocLink(link: String?): String =
+        if (link != null) link.substringBefore('(').replace('#', '.') else ""
+
+    private fun PsiDocTag.linkElement(): PsiElement? =
+            getValueElement() ?: getDataElements().firstOrNull { it !is PsiWhiteSpace }
+
+    private class HtmlToMarkdownConverter() : XmlRecursiveElementVisitor() {
+        private enum class ListType { Ordered; Unordered }
+        data class MarkdownSpan(val prefix: String, val suffix: String) {
+            class object {
+                val Empty = MarkdownSpan("", "")
+
+                fun wrap(text: String) = MarkdownSpan(text, text)
+                fun prefix(text: String) = MarkdownSpan(text, "")
+            }
+        }
+
+
+        val result: String
+            get() = markdownBuilder.toString()
+
+        private val markdownBuilder = StringBuilder("/**")
+        private var afterLineBreak = false
+        private var whitespaceIsPartOfText = true
+        private var currentListType = ListType.Unordered
+
+        override fun visitWhiteSpace(space: PsiWhiteSpace) {
+            super.visitWhiteSpace(space)
+
+            if (whitespaceIsPartOfText) {
+                appendPendingText()
+                markdownBuilder.append(space.getText())
+                if (space.textContains('\n')) {
+                    afterLineBreak = true
+                }
+            }
+        }
+
+        override fun visitElement(element: PsiElement) {
+            super.visitElement(element)
+
+            val tokenType = element.getNode().getElementType()
+            if (tokenType == XmlTokenType.XML_DATA_CHARACTERS || tokenType == XmlTokenType.XML_CHAR_ENTITY_REF) {
+                appendPendingText()
+                markdownBuilder.append(element.getText())
+            }
+        }
+
+        override fun visitXmlTag(tag: XmlTag) {
+            withWhitespaceAsPartOfText(false) {
+                val oldListType = currentListType
+                val atLineStart = afterLineBreak
+                appendPendingText()
+                val (openingMarkdown, closingMarkdown) = getMarkdownForTag(tag, atLineStart)
+                markdownBuilder.append(openingMarkdown)
+
+                super.visitXmlTag(tag)
+
+                markdownBuilder.append(closingMarkdown)
+                currentListType = oldListType
+            }
+        }
+
+        override fun visitXmlText(text: XmlText) {
+            withWhitespaceAsPartOfText(true) {
+                super.visitXmlText(text)
+            }
+        }
+
+        private inline fun withWhitespaceAsPartOfText(newValue: Boolean, block: () -> Unit) {
+            val oldValue = whitespaceIsPartOfText
+            whitespaceIsPartOfText = newValue
+            try {
+                block()
+            }
+            finally {
+                whitespaceIsPartOfText = oldValue
+            }
+        }
+
+        private fun getMarkdownForTag(tag: XmlTag, atLineStart: Boolean): MarkdownSpan = when(tag.getName()) {
+            "b", "strong" -> MarkdownSpan.wrap("**")
+
+            "p" -> if (atLineStart) MarkdownSpan.prefix("\n * ") else MarkdownSpan.prefix("\n *\n *")
+
+            "i", "em" -> MarkdownSpan.wrap("*")
+
+            "s", "del" -> MarkdownSpan.wrap("~~")
+
+            "code" -> MarkdownSpan.wrap("`")
+
+            "a" -> {
+                if (tag.getAttributeValue("docref") != null) {
+                    val docRef = tag.getAttributeValue("docref")
+                    val innerText = tag.getValue().getText()
+                    if (docRef == innerText) MarkdownSpan("[", "]") else MarkdownSpan("[", "][$docRef]")
+                }
+                else {
+                    MarkdownSpan("[", "](${tag.getAttributeValue("href")})")
+                }
+            }
+
+            "ul" -> { currentListType = ListType.Unordered; MarkdownSpan.Empty }
+
+            "ol" -> { currentListType = ListType.Ordered; MarkdownSpan.Empty }
+
+            "li" -> if (currentListType == ListType.Unordered) MarkdownSpan.prefix(" * ") else MarkdownSpan.prefix(" 1. ")
+
+            else -> MarkdownSpan.Empty
+        }
+
+        private fun appendPendingText() {
+            if (afterLineBreak ) {
+                markdownBuilder.append(" * ")
+                afterLineBreak = false
+            }
+        }
+
+        override fun visitXmlFile(file: XmlFile) {
+            super.visitXmlFile(file)
+
+            markdownBuilder.append(" */")
+        }
+    }
+}
+
+fun PsiDocTag.content(): String =
+    getChildren()
+            .dropWhile { it.getNode().getElementType() == JavaDocTokenType.DOC_TAG_NAME }
+            .dropWhile { it is PsiWhiteSpace }
+            .filterNot { it.getNode().getElementType() == JavaDocTokenType.DOC_COMMENT_LEADING_ASTERISKS }
+            .map { it.getText() }
+            .join("")
@@ -0,0 +1,6 @@
+/**
+ * This is a deprecated class.
+ * @deprecated do not use
+ */
+class C {
+}
@@ -0,0 +1,5 @@
+/**
+ * This is a deprecated class.
+ */
+deprecated("do not use")
+class C
@@ -0,0 +1,4 @@
+/**
+ * @param T This is the <b>parameter</b> of class {@code C}
+ */
+class C<T> {}
@@ -0,0 +1,4 @@
+/**
+ * @param T This is the **parameter** of class `C`
+ */
+class C<T>
@@ -0,0 +1,16 @@
+/**
+ * We support the following HTML styles: <b>bold</b>, <i>italic</i>, <s>strikethrough</s>, <code>code</code>
+ * <p>Paragraph tags also work.</p>
+ * HTML entities (need to remain as is in Markdown): &amp; &lt; &gt; &quot;
+ * Made by <a href="http://www.jetbrains.com">JetBrains</a>
+ * <ul>
+ *     <li>Kotlin</li>
+ *     <li>Java</li>
+ * </ul>
+ * <ol>
+ *     <li>First</li>
+ *     <li>Second</li>
+ * </ol>
+ */
+public class C {
+}
@@ -0,0 +1,16 @@
+/**
+ * We support the following HTML styles: **bold**, *italic*, ~~strikethrough~~, `code`
+ *
+ * Paragraph tags also work.
+ * HTML entities (need to remain as is in Markdown): &amp; &lt; &gt; &quot;
+ * Made by [JetBrains](http://www.jetbrains.com)
+ *
+ *  * Kotlin
+ *  * Java
+ *
+ *
+ *  1. First
+ *  1. Second
+ *
+ */
+public class C
@@ -0,0 +1,5 @@
+/**
+ * {@code A<B}
+ */
+public class C {
+}
@@ -0,0 +1,4 @@
+/**
+ * `A&lt;B`
+ */
+public class C
@@ -0,0 +1,7 @@
+/**
+ * {@link C#foo(int)}
+ */
+class C {
+    void foo(int i) {
+    }
+}
@@ -0,0 +1,7 @@
+/**
+ * [C.foo]
+ */
+class C {
+    fun foo(i: Int) {
+    }
+}
@@ -0,0 +1,7 @@
+/**
+ * {@link C#foo(int) the best foo method ever}
+ */
+class C {
+    void foo(int i) {
+    }
+}
@@ -0,0 +1,7 @@
+/**
+ * [the best foo method ever][C.foo]
+ */
+class C {
+    fun foo(i: Int) {
+    }
+}
@@ -0,0 +1,5 @@
+/**
+ * @deprecated do not use
+ */
+class C {
+}
@@ -0,0 +1,2 @@
+deprecated("do not use")
+class C
@@ -0,0 +1,7 @@
+/**
+ * @see C#foo(int)
+ */
+class C {
+    void foo(int i) {
+    }
+}
@@ -0,0 +1,7 @@
+/**
+ * @see C.foo
+ */
+class C {
+    fun foo(i: Int) {
+    }
+}
@@ -51,6 +51,7 @@ import java.util.regex.Pattern;
        JavaToKotlinConverterForWebDemoTestGenerated.ContinueStatement.class,
        JavaToKotlinConverterForWebDemoTestGenerated.DeclarationStatement.class,
        JavaToKotlinConverterForWebDemoTestGenerated.DoWhileStatement.class,
+        JavaToKotlinConverterForWebDemoTestGenerated.DocComments.class,
        JavaToKotlinConverterForWebDemoTestGenerated.DropAccessors.class,
        JavaToKotlinConverterForWebDemoTestGenerated.Enum.class,
        JavaToKotlinConverterForWebDemoTestGenerated.Equals.class,
@@ -1368,6 +1369,63 @@ public class JavaToKotlinConverterForWebDemoTestGenerated extends AbstractJavaTo
        }
    }

+    @TestMetadata("j2k/testData/fileOrElement/docComments")
+    @TestDataPath("$PROJECT_ROOT")
+    @RunWith(JUnit3RunnerWithInners.class)
+    public static class DocComments extends AbstractJavaToKotlinConverterForWebDemoTest {
+        public void testAllFilesPresentInDocComments() throws Exception {
+            JetTestUtils.assertAllTestsPresentByMetadata(this.getClass(), new File("j2k/testData/fileOrElement/docComments"), Pattern.compile("^(.+)\\.java$"), true);
+        }
+
+        @TestMetadata("deprecatedDocTag.java")
+        public void testDeprecatedDocTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/deprecatedDocTag.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("docCommentWithParamTag.java")
+        public void testDocCommentWithParamTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/docCommentWithParamTag.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("htmlInDocComment.java")
+        public void testHtmlInDocComment() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/htmlInDocComment.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("inlineTagsInDocComment.java")
+        public void testInlineTagsInDocComment() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/inlineTagsInDocComment.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("linkTag.java")
+        public void testLinkTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/linkTag.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("linkTagWithLabel.java")
+        public void testLinkTagWithLabel() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/linkTagWithLabel.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("onlyDeprecatedDocTag.java")
+        public void testOnlyDeprecatedDocTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/onlyDeprecatedDocTag.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("seeTag.java")
+        public void testSeeTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/seeTag.java");
+            doTest(fileName);
+        }
+    }
+
    @TestMetadata("j2k/testData/fileOrElement/dropAccessors")
    @TestDataPath("$PROJECT_ROOT")
    @RunWith(JUnit3RunnerWithInners.class)
@@ -51,6 +51,7 @@ import java.util.regex.Pattern;
        JavaToKotlinConverterSingleFileTestGenerated.ContinueStatement.class,
        JavaToKotlinConverterSingleFileTestGenerated.DeclarationStatement.class,
        JavaToKotlinConverterSingleFileTestGenerated.DoWhileStatement.class,
+        JavaToKotlinConverterSingleFileTestGenerated.DocComments.class,
        JavaToKotlinConverterSingleFileTestGenerated.DropAccessors.class,
        JavaToKotlinConverterSingleFileTestGenerated.Enum.class,
        JavaToKotlinConverterSingleFileTestGenerated.Equals.class,
@@ -1368,6 +1369,63 @@ public class JavaToKotlinConverterSingleFileTestGenerated extends AbstractJavaTo
        }
    }

+    @TestMetadata("j2k/testData/fileOrElement/docComments")
+    @TestDataPath("$PROJECT_ROOT")
+    @RunWith(JUnit3RunnerWithInners.class)
+    public static class DocComments extends AbstractJavaToKotlinConverterSingleFileTest {
+        public void testAllFilesPresentInDocComments() throws Exception {
+            JetTestUtils.assertAllTestsPresentByMetadata(this.getClass(), new File("j2k/testData/fileOrElement/docComments"), Pattern.compile("^(.+)\\.java$"), true);
+        }
+
+        @TestMetadata("deprecatedDocTag.java")
+        public void testDeprecatedDocTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/deprecatedDocTag.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("docCommentWithParamTag.java")
+        public void testDocCommentWithParamTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/docCommentWithParamTag.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("htmlInDocComment.java")
+        public void testHtmlInDocComment() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/htmlInDocComment.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("inlineTagsInDocComment.java")
+        public void testInlineTagsInDocComment() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/inlineTagsInDocComment.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("linkTag.java")
+        public void testLinkTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/linkTag.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("linkTagWithLabel.java")
+        public void testLinkTagWithLabel() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/linkTagWithLabel.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("onlyDeprecatedDocTag.java")
+        public void testOnlyDeprecatedDocTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/onlyDeprecatedDocTag.java");
+            doTest(fileName);
+        }
+
+        @TestMetadata("seeTag.java")
+        public void testSeeTag() throws Exception {
+            String fileName = JetTestUtils.navigationMetadata("j2k/testData/fileOrElement/docComments/seeTag.java");
+            doTest(fileName);
+        }
+    }
+
    @TestMetadata("j2k/testData/fileOrElement/dropAccessors")
    @TestDataPath("$PROJECT_ROOT")
    @RunWith(JUnit3RunnerWithInners.class)