path: root/dokka-subprojects/plugin-base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt

/*
 * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 */

package translators

import org.jetbrains.dokka.DokkaConfiguration
import org.jetbrains.dokka.base.signatures.KotlinSignatureUtils.modifiers
import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
import org.jetbrains.dokka.links.DRI
import org.jetbrains.dokka.links.PointingToDeclaration
import org.jetbrains.dokka.model.*
import org.jetbrains.dokka.model.doc.*
import utils.text
import kotlin.test.*
import utils.OnlyDescriptors

class DefaultDescriptorToDocumentableTranslatorTest : BaseAbstractTest() {
    val configuration = dokkaConfiguration {
        suppressObviousFunctions = false
        sourceSets {
            sourceSet {
                sourceRoots = listOf("src/main/kotlin")
                classpath = listOf(commonStdlibPath!!, jvmStdlibPath!!)
            }
        }
    }

    @Suppress("DEPRECATION") // for includeNonPublic
    val javaConfiguration = dokkaConfiguration {
        sourceSets {
            sourceSet {
                sourceRoots = listOf("src/main/java")
                includeNonPublic = true
            }
        }
    }

    @Test
    fun `data class kdocs over generated methods`() {
        testInline(
            """
            |/src/main/kotlin/sample/XD.kt
            |package sample
            |/**
            | * But the fat Hobbit, he knows. Eyes always watching.
            | */
            |data class XD(val xd: String) {
            |   /**
            |    * But the fat Hobbit, he knows. Eyes always watching.
            |    */
            |   fun custom(): String = ""
            |
            |   /**
            |    * Memory is not what the heart desires. That is only a mirror.
            |    */
            |   override fun equals(other: Any?): Boolean = true
            |}
            """.trimIndent(),
            configuration
        ) {
            documentablesMergingStage = { module ->
                assertEquals("", module.documentationOf("XD", "copy"))
                assertEquals(
                    "Memory is not what the heart desires. That is only a mirror.",
                    module.documentationOf(
                        "XD",
                        "equals"
                    )
                )
                assertEquals("", module.documentationOf("XD", "hashCode"))
                assertEquals("", module.documentationOf("XD", "toString"))
                assertEquals("But the fat Hobbit, he knows. Eyes always watching.", module.documentationOf("XD", "custom"))
            }
        }
    }

    @Test
    fun `simple class kdocs`() {
        testInline(
            """
            |/src/main/kotlin/sample/XD.kt
            |package sample
            |/**
            | * But the fat Hobbit, he knows. Eyes always watching.
            | */
            |class XD(val xd: String) {
            |   /**
            |    * But the fat Hobbit, he knows. Eyes always watching.
            |    */
            |   fun custom(): String = ""
            |
            |   /**
            |    * Memory is not what the heart desires. That is only a mirror.
            |    */
            |   override fun equals(other: Any?): Boolean = true
            |}
            """.trimIndent(),
            configuration
        ) {
            documentablesMergingStage = { module ->
                assertEquals("But the fat Hobbit, he knows. Eyes always watching.", module.documentationOf("XD", "custom"))
                assertEquals(
                    "Memory is not what the heart desires. That is only a mirror.",
                    module.documentationOf(
                        "XD",
                        "equals"
                    )
                )
            }
        }
    }

    @Test
    fun `kdocs with code block`() {
        testInline(
            """
            |/src/main/kotlin/sample/TestForCodeInDocs.kt
            |package sample
            |/**
            | * Utility for building a String that represents an XML document.
            | * The XmlBlob object is immutable and the passed values are copied where it makes sense.
            | *
            | * Note the XML Declaration is not output as part of the XmlBlob
            | *
            | * 
            | *    val soapAttrs = attrs("soap-env" to "http://www.w3.org/2001/12/soap-envelope",
            | *        "soap-env:encodingStyle" to "http://www.w3.org/2001/12/soap-encoding")
            | *    val soapXml = node("soap-env:Envelope", soapAttrs,
            | *        node("soap-env:Body", attrs("xmlns:m" to "http://example"),
            | *            node("m:GetExample",
            | *                node("m:GetExampleName", "BasePair")
            | *            )
            | *        )
            | *    )
            | *
            | *
            | */
            |class TestForCodeInDocs {
            |}
        """.trimIndent(), configuration
        ) {
            documentablesMergingStage = { module ->
                val description = module.descriptionOf("TestForCodeInDocs")
                val expected = listOf(
                    P(
                        children = listOf(Text("Utility for building a String that represents an XML document. The XmlBlob object is immutable and the passed values are copied where it makes sense."))
                    ),
                    P(
                        children = listOf(Text("Note the XML Declaration is not output as part of the XmlBlob"))
                    ),
                    CodeBlock(
                        children = listOf(
                            Text(
                                """val soapAttrs = attrs("soap-env" to "http://www.w3.org/2001/12/soap-envelope",
    "soap-env:encodingStyle" to "http://www.w3.org/2001/12/soap-encoding")
val soapXml = node("soap-env:Envelope", soapAttrs,
    node("soap-env:Body", attrs("xmlns:m" to "http://example"),
        node("m:GetExample",
            node("m:GetExampleName", "BasePair")
        )
    )
)"""
                            )
                        )
                    )