Javadoc @inheritDoc tag support (#1608)

2 files changed, 556 insertions, 0 deletions

diff --git a/plugins/base/src/test/kotlin/translators/JavadocInheritDocsTest.kt b/plugins/base/src/test/kotlin/translators/JavadocInheritDocsTest.kt
new file mode 100644
index 00000000..8fac13c9
--- /dev/null
+++ b/plugins/base/src/test/kotlin/translators/JavadocInheritDocsTest.kt
@@ -0,0 +1,309 @@
+package translators
+
+import org.jetbrains.dokka.model.doc.CustomDocTag
+import org.jetbrains.dokka.model.doc.Description
+import org.jetbrains.dokka.model.doc.P
+import org.jetbrains.dokka.model.doc.Text
+import org.jetbrains.dokka.testApi.testRunner.AbstractCoreTest
+import org.junit.Ignore
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Disabled
+import org.junit.jupiter.api.Test
+
+class JavadocInheritDocsTest : AbstractCoreTest() {
+    val configuration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/main/java")
+            }
+        }
+    }
+
+    @Test
+    fun `work when whole description is inherited`() {
+        testInline(
+            """
+            |/src/main/java/sample/Superclass.java
+            |package sample;
+            |/**
+            |* Superclass docs
+            |*/
+            |public class Superclass { }
+            |
+            |/src/main/java/sample/Subclass.java
+            |package sample;
+            |/**
+            |* {@inheritDoc}
+            |*/
+            |public class Subclass extends Superclass { }
+            """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val subclass = module.findClasslike("sample", "Subclass")
+                val descriptionGot = subclass.documentation.values.first().children.first()
+                val expectedDescription = Description(
+                    CustomDocTag(
+                        children = listOf(
+                            P(
+                                children = listOf(Text("Superclass docs"))
+                            )
+                        ),
+                        name = "MARKDOWN_FILE"
+                    )
+                )
+
+                assertEquals(expectedDescription, descriptionGot)
+            }
+        }
+    }
+
+    @Test
+    fun `work when inherited part is inside description`() {
+        testInline(
+            """
+            |/src/main/java/sample/Superclass.java
+            |package sample;
+            |/**
+            |* Superclass docs
+            |*/
+            |public class Superclass { }
+            |
+            |/src/main/java/sample/Subclass.java
+            |package sample;
+            |/**
+            |* Subclass docs. {@inheritDoc} End of subclass docs
+            |*/
+            |public class Subclass extends Superclass { }
+            """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val subclass = module.findClasslike("sample", "Subclass")
+                val descriptionGot = subclass.documentation.values.first().children.first()
+                val expectedDescription = Description(
+                    CustomDocTag(
+                        children = listOf(
+                            P(
+                                children = listOf(Text("Subclass docs. Superclass docs End of subclass docs"))
+                            )
+                        ),
+                        name = "MARKDOWN_FILE"
+                    )
+                )
+
+                assertEquals(expectedDescription, descriptionGot)
+            }
+        }
+    }
+
+    @Test
+    fun `work when inherited part is empty`() {
+        testInline(
+            """
+            |/src/main/java/sample/Superclass.java
+            |package sample;
+            |public class Superclass { }
+            |
+            |/src/main/java/sample/Subclass.java
+            |package sample;
+            |/**
+            |* Subclass docs. {@inheritDoc} End of subclass docs
+            |*/
+            |public class Subclass extends Superclass { }
+            """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val subclass = module.findClasslike("sample", "Subclass")
+                val descriptionGot = subclass.documentation.values.first().children.first()
+                val expectedDescription = Description(
+                    CustomDocTag(
+                        children = listOf(
+                            P(
+                                children = listOf(Text("Subclass docs. End of subclass docs"))
+                            )
+                        ),
+                        name = "MARKDOWN_FILE"
+                    )
+                )
+
+                assertEquals(expectedDescription, descriptionGot)
+            }
+        }
+    }
+
+    @Test
+    @Disabled("This should be enabled when we have proper tag inheritance in javadoc parser")
+    fun `work when inherited part is empty in supertype but present in its supertype`() {
+        testInline(
+            """
+            |/src/main/java/sample/SuperSuperclass.java
+            |package sample;
+            |/**
+            |* Super super docs
+            |*/
+            |public class SuperSuperclass { }
+            |/src/main/java/sample/Superclass.java
+            |package sample;
+            |public class Superclass extends SuperSuperClass { }
+            |
+            |/src/main/java/sample/Subclass.java
+            |package sample;
+            |/**
+            |* Subclass docs. {@inheritDoc} End of subclass docs
+            |*/
+            |public class Subclass extends Superclass { }
+            """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val subclass = module.findClasslike("sample", "Subclass")
+                val descriptionGot = subclass.documentation.values.first().children.first()
+                val expectedDescription = Description(
+                    CustomDocTag(
+                        children = listOf(
+                            P(
+                                children = listOf(Text("Subclass docs. Super super docs End of subclass docs"))
+                            )
+                        ),
+                        name = "MARKDOWN_FILE"
+                    )
+                )
+
+                assertEquals(expectedDescription, descriptionGot)
+            }
+        }
+    }
+
+    @Test
+    //Original javadoc doesn't treat interfaces as valid candidates for inherit doc
+    fun `work with interfaces`() {
+        testInline(
+            """
+            |/src/main/java/sample/SuperInterface.java
+            |package sample;
+            |/**
+            |* Super super docs
+            |*/
+            |public interface SuperInterface { }
+            |
+            |/src/main/java/sample/Subclass.java
+            |package sample;
+            |/**
+            |* Subclass docs. {@inheritDoc} End of subclass docs
+            |*/
+            |public interface Subclass extends SuperInterface { }
+            """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val subclass = module.findClasslike("sample", "Subclass")
+                val descriptionGot = subclass.documentation.values.first().children.first()
+                val expectedDescription = Description(
+                    CustomDocTag(
+                        children = listOf(
+                            P(
+                                children = listOf(Text("Subclass docs. End of subclass docs"))
+                            )
+                        ),
+                        name = "MARKDOWN_FILE"
+                    )
+                )
+
+                assertEquals(expectedDescription, descriptionGot)
+            }
+        }
+    }
+
+
+    @Test
+    fun `work with multiple supertypes`() {
+        testInline(
+            """
+            |/src/main/java/sample/SuperInterface.java
+            |package sample;
+            |/**
+            |* Super interface docs
+            |*/
+            |public interface SuperInterface { }
+            |/src/main/java/sample/Superclass.java
+            |package sample;
+            |/**
+            |* Super class docs
+            |*/
+            |public class Superclass { }
+            |
+            |/src/main/java/sample/Subclass.java
+            |package sample;
+            |/**
+            |* Subclass docs. {@inheritDoc} End of subclass docs
+            |*/
+            |public class Subclass extends Superclass implements SuperInterface { }
+            """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val subclass = module.findClasslike("sample", "Subclass")
+                val descriptionGot = subclass.documentation.values.first().children.first()
+                val expectedDescription = Description(
+                    CustomDocTag(
+                        children = listOf(
+                            P(
+                                children = listOf(Text("Subclass docs. Super class docs End of subclass docs"))
+                            )
+                        ),
+                        name = "MARKDOWN_FILE"
+                    )
+                )
+
+                assertEquals(expectedDescription, descriptionGot)
+            }
+        }
+    }
+
+    @Test
+    fun `work with methods`() {
+        testInline(
+            """
+            |/src/main/java/sample/Superclass.java
+            |package sample;
+            |public class Superclass {
+            |/**
+            |* Sample super method
+            |*
+            |* @return super string
+            |* @throws RuntimeException super throws
+            |* @see java.lang.String super see
+            |* @deprecated super deprecated
+            |*/
+            |public String test() {
+            |    return "";
+            |}
+            |}
+            |/src/main/java/sample/Subclass.java
+            |package sample;
+            |class Subclass extends Superclass {
+            |    /**
+            |     * Sample sub method. {@inheritDoc}
+            |     */
+            |    @Override
+            |    public String test() {
+            |        return super.test();
+            |    }
+            |}
+            """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val function = module.findFunction("sample", "Subclass", "test")
+                val descriptionGot = function.documentation.values.first().children.first()
+                val expectedDescription = Description(
+                    CustomDocTag(
+                        children = listOf(
+                            P(
+                                children = listOf(Text("Sample sub method. Sample super method"))
+                            )
+                        ),
+                        name = "MARKDOWN_FILE"
+                    )
+                )
+
+                assertEquals(expectedDescription, descriptionGot)
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/plugins/base/src/test/kotlin/translators/JavadocInheritedDocTagsTest.kt b/plugins/base/src/test/kotlin/translators/JavadocInheritedDocTagsTest.kt
new file mode 100644
index 00000000..a7d4f057
--- /dev/null
+++ b/plugins/base/src/test/kotlin/translators/JavadocInheritedDocTagsTest.kt
@@ -0,0 +1,247 @@
+package translators
+
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.links.PointingToDeclaration
+import org.jetbrains.dokka.model.DModule
+import org.jetbrains.dokka.model.doc.*
+import org.jetbrains.dokka.testApi.testRunner.AbstractCoreTest
+import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstance
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Test
+import org.jetbrains.dokka.model.doc.Deprecated as DokkaDeprecatedTag
+import org.jetbrains.dokka.model.doc.Throws as DokkaThrowsTag
+
+class JavadocInheritedDocTagsTest : AbstractCoreTest() {
+    private val configuration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/main/java")
+            }
+        }
+    }
+
+    private fun performTagsTest(test: (DModule) -> Unit) {
+        testInline(
+            """
+            |/src/main/java/sample/Superclass.java
+            |package sample;
+            |/**
+            |* @author super author
+            |*/
+            |class Superclass {
+            |    /**
+            |     * Sample super method
+            |     *
+            |     * @return super string
+            |     * @throws RuntimeException super throws
+            |     * @see java.lang.String super see
+            |     * @deprecated super deprecated
+            |     */
+            |    public String test(){
+            |        return "";
+            |    }
+            |
+            |     /**
+            |      *
+            |      * @param xd String superclass
+            |      * @param asd Integer superclass
+            |      */
+            |    public void test2(String xd, Integer asd){
+            |    }
+            |}
+            |/src/main/java/sample/Subclass.java
+            |package sample;
+            |/**
+            |* @author Ja, {@inheritDoc}
+            |*/
+            |class Subclass extends Superclass {
+            |/**
+            | * Sample sub method. {@inheritDoc}
+            | *
+            | * @return "sample string". {@inheritDoc}
+            | * @throws RuntimeException because i can, {@inheritDoc}
+            | * @throws IllegalStateException this should be it {@inheritDoc}
+            | * @see java.lang.String string, {@inheritDoc}
+            | * @deprecated do not use, {@inheritDoc}
+            | */
+            | @Override
+            | public String test() {
+            |    return super.test();
+            | }
+            |
+            |    /**
+            |     *
+            |     * @param asd2 integer subclass, {@inheritDoc}
+            |     * @param xd2 string subclass, {@inheritDoc}
+            |     */
+            |    public void test2(String xd2, Integer asd2){
+            |    }
+            |}
+            """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = test
+        }
+    }
+
+    @Test
+    fun `work with return`() {
+        performTagsTest { module ->
+            val function = module.findFunction("sample", "Subclass", "test")
+            val renderedTag = function.documentation.values.first().children.firstIsInstance<Return>()
+            val expectedTag = Return(
+                CustomDocTag(
+                    children = listOf(
+                        P(
+                            children = listOf(Text("\"sample string\". super string"))
+                        )
+                    ),
+                    name = "MARKDOWN_FILE"
+                )
+            )
+
+            assertEquals(expectedTag, renderedTag)
+        }
+    }
+
+    @Test
+    fun `work with throws`() {
+        performTagsTest { module ->
+            val function = module.findFunction("sample", "Subclass", "test")
+            val renderedTag =
+                function.documentation.values.first().children.first { it is DokkaThrowsTag && it.name == "java.lang.RuntimeException" }
+            val expectedTag = DokkaThrowsTag(
+                CustomDocTag(
+                    children = listOf(
+                        P(
+                            children = listOf(Text("because i can, super throws"))
+                        )
+                    ),
+                    name = "MARKDOWN_FILE"
+                ),
+                "java.lang.RuntimeException",
+                DRI("java.lang", "RuntimeException", target = PointingToDeclaration)
+            )
+
+            assertEquals(expectedTag, renderedTag)
+        }
+    }
+
+    @Test
+    fun `work with throws when exceptions are different`() {
+        performTagsTest { module ->
+            val function = module.findFunction("sample", "Subclass", "test")
+            val renderedTag =
+                function.documentation.values.first().children.first { it is DokkaThrowsTag && it.name == "java.lang.IllegalStateException" }
+            val expectedTag = DokkaThrowsTag(
+                CustomDocTag(
+                    children = listOf(
+                        P(
+                            children = listOf(Text("this should be it"))
+                        )
+                    ),
+                    name = "MARKDOWN_FILE"
+                ),
+                "java.lang.IllegalStateException",
+                DRI("java.lang", "IllegalStateException", target = PointingToDeclaration)
+            )
+
+            assertEquals(expectedTag, renderedTag)
+        }
+    }
+
+    @Test
+    fun `work with deprecated`() {
+        performTagsTest { module ->
+            val function = module.findFunction("sample", "Subclass", "test")
+            val renderedTag = function.documentation.values.first().children.firstIsInstance<DokkaDeprecatedTag>()
+            val expectedTag = DokkaDeprecatedTag(
+                CustomDocTag(
+                    children = listOf(
+                        P(
+                            children = listOf(Text("do not use, Sample super method"))
+                        )
+                    ),
+                    name = "MARKDOWN_FILE"
+                ),
+            )
+
+            assertEquals(expectedTag, renderedTag)
+        }
+    }
+
+    @Test
+    fun `work with see also`() {
+        performTagsTest { module ->
+            val function = module.findFunction("sample", "Subclass", "test")
+            val renderedTag = function.documentation.values.first().children.firstIsInstance<See>()
+            val expectedTag = See(
+                CustomDocTag(
+                    children = listOf(
+                        P(
+                            children = listOf(Text("string,"))
+                        )
+                    ),
+                    name = "MARKDOWN_FILE"
+                ),
+                "java.lang.String",
+                DRI("java.lang", "String")
+            )
+
+            assertEquals(expectedTag, renderedTag)
+        }
+    }
+
+    @Test
+    fun `work with author`() {
+        performTagsTest { module ->
+            val classlike = module.findClasslike("sample", "Subclass")
+            val renderedTag = classlike.documentation.values.first().children.firstIsInstance<Author>()
+            val expectedTag = Author(
+                CustomDocTag(
+                    children = listOf(
+                        P(
+                            children = listOf(Text("Ja, super author"))
+                        )
+                    ),
+                    name = "MARKDOWN_FILE"
+                ),
+            )
+
+            assertEquals(expectedTag, renderedTag)
+        }
+    }
+
+    @Test
+    fun `work with params`() {
+        performTagsTest { module ->
+            val function = module.findFunction("sample", "Subclass", "test2")
+            val (asdTag, xdTag) = function.documentation.values.first().children.filterIsInstance<Param>()
+                .sortedBy { it.name }
+
+            val expectedAsdTag = Param(
+                CustomDocTag(
+                    children = listOf(
+                        P(
+                            children = listOf(Text("integer subclass, Integer superclass"))
+                        )
+                    ),
+                    name = "MARKDOWN_FILE"
+                ),
+                "asd2"
+            )
+            val expectedXdTag = Param(
+                CustomDocTag(
+                    children = listOf(
+                        P(
+                            children = listOf(Text("string subclass, String superclass"))
+                        )
+                    ),
+                    name = "MARKDOWN_FILE"
+                ),
+                "xd2"
+            )
+            assertEquals(expectedAsdTag, asdTag)
+            assertEquals(expectedXdTag, xdTag)
+        }
+    }
+}
\ No newline at end of file