Skip to content

Commit

Permalink
Display Java's Deprecated message (#3421)
Browse files Browse the repository at this point in the history
  • Loading branch information
@IgnatBeresnev
IgnatBeresnev authored Sep 9, 2024
1 parent 3bc5ae3 commit 51ddab5
Show file tree
Hide file tree
Showing 4 changed files with 140 additions and 36 deletions.
14 changes: 13 additions & 1 deletion ...in/kotlin/org/jetbrains/dokka/base/translators/documentables/DeprecationSectionCreator.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import org.jetbrains.dokka.base.signatures.KotlinSignatureUtils.annotations
import org.jetbrains.dokka.base.transformers.documentables.isDeprecated
import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder
import org.jetbrains.dokka.model.*
import org.jetbrains.dokka.model.doc.Deprecated
import org.jetbrains.dokka.pages.ContentKind
import org.jetbrains.dokka.pages.ContentStyle
import org.jetbrains.dokka.pages.TextStyle
Expand Down Expand Up @@ -48,7 +49,7 @@ internal fun PageContentBuilder.DocumentableContentBuilder.deprecatedSectionCont
if (kotlinAnnotation != null) {
createKotlinDeprecatedSectionContent(kotlinAnnotation, platformAnnotations)
} else if (javaAnnotation != null) {
createJavaDeprecatedSectionContent(javaAnnotation)
createJavaDeprecatedSectionContent(javaAnnotation, documentable)
}
}
}
Expand Down Expand Up @@ -174,6 +175,7 @@ private fun DocumentableContentBuilder.createReplaceWithSectionContent(kotlinDep
*/
private fun DocumentableContentBuilder.createJavaDeprecatedSectionContent(
deprecatedAnnotation: Annotations.Annotation,
documentable: Documentable,
) {
val isForRemoval = deprecatedAnnotation.takeBooleanParam("forRemoval", default = false)
header(
Expand All @@ -185,6 +187,16 @@ private fun DocumentableContentBuilder.createJavaDeprecatedSectionContent(
text("Since version $it")
}
}

// Java projects should only have a single source set
val documentation = documentable.documentation.values.firstOrNull() ?: return

// Javadoc takes the first @depracted tag, and skips all subsequent duplicates
val deprecatedJavadocTag = documentation.childrenOfType<Deprecated>().firstOrNull() ?: return

group(styles = setOf(TextStyle.Paragraph)) {
comment(deprecatedJavadocTag.root)
}
}

private fun Annotations.Annotation.takeBooleanParam(name: String, default: Boolean): Boolean =
Expand Down
3 changes: 2 additions & 1 deletion ...src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DescriptionSections.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import org.jetbrains.dokka.model.Documentable
import org.jetbrains.dokka.model.SourceSetDependent
import org.jetbrains.dokka.model.WithScope
import org.jetbrains.dokka.model.doc.*
import org.jetbrains.dokka.model.doc.Deprecated
import org.jetbrains.dokka.model.orEmpty
import org.jetbrains.dokka.model.properties.WithExtraProperties
import org.jetbrains.dokka.pages.ContentKind
Expand All @@ -26,7 +27,7 @@ import kotlin.reflect.full.isSubclassOf
internal const val KDOC_TAG_HEADER_LEVEL = 4

private val unnamedTagsExceptions: Set<KClass<out TagWrapper>> =
setOf(Property::class, Description::class, Constructor::class, Param::class, See::class)
setOf(Property::class, Description::class, Constructor::class, Param::class, See::class, Deprecated::class)

internal fun PageContentBuilder.DocumentableContentBuilder.descriptionSectionContent(
documentable: Documentable,
Expand Down
84 changes: 77 additions & 7 deletions dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,8 @@ import org.jetbrains.dokka.model.Documentable
import org.jetbrains.dokka.model.properties.WithExtraProperties
import org.jetbrains.dokka.pages.ContentPage
import org.jetbrains.dokka.pages.ContentStyle
import utils.pWrapped
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
import utils.*
import kotlin.test.*

class JavaDeprecatedTest : BaseAbstractTest() {

Expand Down Expand Up @@ -68,7 +65,7 @@ class JavaDeprecatedTest : BaseAbstractTest() {
|package deprecated
|
|/**
| * Average function description
| * Average class description
| */
|@Deprecated(forRemoval = true)
|public class DeprecatedJavaClass {}
Expand All @@ -90,7 +87,7 @@ class JavaDeprecatedTest : BaseAbstractTest() {
+"Deprecated (for removal)"
}
}
group { pWrapped("Average function description") }
group { pWrapped("Average class description") }
}
}
skipAllNotMatching()
Expand Down Expand Up @@ -141,4 +138,77 @@ class JavaDeprecatedTest : BaseAbstractTest() {
}
}
}

@Test
fun `should take deprecation message from @deprecated javadoc tag`() {
testInline(
"""
|/src/main/kotlin/deprecated/DeprecatedJavaClass.java
|package deprecated
|
|public class DeprecatedJClass {
| /**
| * Don't do anything
| * @deprecated
| * This method is no longer acceptable to compute time between versions.
| * <p>Use {@link DeprecatedJClass#getStringMethodNew()} instead.</p>
| */
| @Deprecated(since = "18.0.2", forRemoval = true)
| public void getStringMethod(){}
|}
""".trimIndent(),
testConfiguration
) {
pagesTransformationStage = { module ->
val deprecatedFunction = module.children
.single { it.name == "deprecated" }.children
.single { it.name == "DeprecatedJClass" }.children
.single { it.name == "getStringMethod" } as ContentPage

deprecatedFunction.content.assertNode {
group {
header(1) { +"getStringMethod" }
}
divergentGroup {
divergentInstance {
divergent {
bareSignature(
annotations = emptyMap(),
visibility = "",
modifier = "open",
keywords = emptySet(),
name = "getStringMethod",
returnType = null
)
}
after {
group {
header(3) {
+"Deprecated (for removal)"
}
group {
check { assertEquals(ContentStyle.Footnote, this.style.firstOrNull()) }
+"Since version 18.0.2"
}
p {
comment {
p {
+"Thismethod is no longer acceptable to compute time between versions. "
}
p {
+"Use "
+"getStringMethodNew"
+" instead."
}
}
}
}
group { pWrapped("Don't do anything") }
}
}
}
}
}
}
}
}
75 changes: 48 additions & 27 deletions dokka-subprojects/plugin-base/src/test/kotlin/content/params/ContentForParamsTest.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,7 @@ class ContentForParamsTest : BaseAbstractTest() {
| * {@link java.util.HashMap#containsKey(java.lang.Object) FragmentManager#setFragmentResultListener(String, LifecycleOwner,
| * FragmentResultListener)}.
| */
| @Deprecated
| public class DocGenProcessor {
| public String setTargetFragment(){
| return "";
Expand All @@ -283,6 +284,24 @@ class ContentForParamsTest : BaseAbstractTest() {
group {
skipAllNotMatching() //Signature
}
group {
header(3) {
+"Deprecated"
}
group {
group {
group {
+"Instead of using a target fragment to pass results, the fragment requesting a result should use "
link { +"FragmentManager#setFragmentResult(String, Bundle)" }
+" to deliver results to "
link { +"FragmentResultListener" }
+" instances registered by other fragments via "
link { +"FragmentManager#setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)" }
+"."
}
}
}
}
group {
comment {
+"Return the target fragment set by "
Expand All @@ -292,18 +311,6 @@ class ContentForParamsTest : BaseAbstractTest() {
+"."
}
}
group {
header(4) { +"Deprecated" }
comment {
+"Instead of using a target fragment to pass results, the fragment requesting a result should use "
link { +"FragmentManager#setFragmentResult(String, Bundle)" }
+" to deliver results to "
link { +"FragmentResultListener" }
+" instances registered by other fragments via "
link { +"FragmentManager#setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)" }
+"."
}
}
}
}
skipAllNotMatching()
Expand All @@ -323,6 +330,7 @@ class ContentForParamsTest : BaseAbstractTest() {
| * <a href="https://developer.android.com/guide/navigation/navigation-swipe-view ">
| * TabLayout and ViewPager</a> instead.
| */
| @Deprecated
| public class DocGenProcessor { }
""".trimIndent(), testConfiguration
) {
Expand All @@ -337,11 +345,17 @@ class ContentForParamsTest : BaseAbstractTest() {
skipAllNotMatching() //Signature
}
group {
header(4) { +"Deprecated" }
comment {
+"Use "
link { +"TabLayout and ViewPager" }
+" instead."
header(3) {
+"Deprecated"
}
group {
group {
group {
+"Use "
link { +"TabLayout and ViewPager" }
+" instead."
}
}
}
}
}
Expand Down Expand Up @@ -372,6 +386,7 @@ class ContentForParamsTest : BaseAbstractTest() {
| * {@link java.util.HashMap } to automatically retain the Fragment's
| * non configuration state.
| */
| @Deprecated
| public class DocGenProcessor { }
""".trimIndent(), testConfiguration
) {
Expand All @@ -385,6 +400,22 @@ class ContentForParamsTest : BaseAbstractTest() {
group {
skipAllNotMatching() //Signature
}
group {
header(3) {
+"Deprecated"
}
group {
group {
group {
+"Have your "
link { +"FragmentHostCallback" }
+" implement "
link { +"java.util.HashMap" }
+" to automatically retain the Fragment's non configuration state."
}
}
}
}
group {
comment {
group {
Expand All @@ -399,16 +430,6 @@ class ContentForParamsTest : BaseAbstractTest() {
}
}
}
group {
header(4) { +"Deprecated" }
comment {
+"Have your "
link { +"FragmentHostCallback" }
+" implement "
link { +"java.util.HashMap" }
+" to automatically retain the Fragment's non configuration state."
}
}
}
}
skipAllNotMatching()
Expand Down

0 comments on commit 51ddab5

Please sign in to comment.