Skip to content

Commit

Permalink
Add deprecation details block (#2622)
Browse files Browse the repository at this point in the history
  • Loading branch information
@IgnatBeresnev
IgnatBeresnev committed Aug 18, 2022
1 parent df8d987 commit 50a3323
Show file tree
Hide file tree
Showing 26 changed files with 1,045 additions and 102 deletions.
2 changes: 2 additions & 0 deletions core/api/core.api
View file
Expand Up @@ -3791,6 +3791,7 @@ public final class org/jetbrains/dokka/pages/ContentKind : java/lang/Enum, org/j
public static final field Companion Lorg/jetbrains/dokka/pages/ContentKind$Companion;
public static final field Constructors Lorg/jetbrains/dokka/pages/ContentKind;
public static final field Cover Lorg/jetbrains/dokka/pages/ContentKind;
public static final field Deprecation Lorg/jetbrains/dokka/pages/ContentKind;
public static final field Empty Lorg/jetbrains/dokka/pages/ContentKind;
public static final field Extensions Lorg/jetbrains/dokka/pages/ContentKind;
public static final field Functions Lorg/jetbrains/dokka/pages/ContentKind;
Expand Down Expand Up @@ -3910,6 +3911,7 @@ public final class org/jetbrains/dokka/pages/ContentResolvedLink : org/jetbrains

public final class org/jetbrains/dokka/pages/ContentStyle : java/lang/Enum, org/jetbrains/dokka/pages/Style {
public static final field Caption Lorg/jetbrains/dokka/pages/ContentStyle;
public static final field Footnote Lorg/jetbrains/dokka/pages/ContentStyle;
public static final field InDocumentationAnchor Lorg/jetbrains/dokka/pages/ContentStyle;
public static final field Indented Lorg/jetbrains/dokka/pages/ContentStyle;
public static final field KDocTag Lorg/jetbrains/dokka/pages/ContentStyle;
Expand Down
2 changes: 2 additions & 0 deletions core/content-matcher-test-utils/api/content-matcher-test-utils.api
View file
Expand Up @@ -15,6 +15,8 @@ public final class matchers/content/ContentMatchersDslKt {
public static final fun br (Lmatchers/content/ContentMatcherBuilder;)V
public static final fun caption (Lmatchers/content/ContentMatcherBuilder;Lkotlin/jvm/functions/Function1;)V
public static final fun check (Lmatchers/content/ContentMatcherBuilder;Lkotlin/jvm/functions/Function1;)V
public static final fun codeBlock (Lmatchers/content/ContentMatcherBuilder;Lkotlin/jvm/functions/Function1;)V
public static final fun codeInline (Lmatchers/content/ContentMatcherBuilder;Lkotlin/jvm/functions/Function1;)V
public static final fun divergent (Lmatchers/content/ContentMatcherBuilder;Lkotlin/jvm/functions/Function1;)V
public static final fun divergentGroup (Lmatchers/content/ContentMatcherBuilder;Lkotlin/jvm/functions/Function1;)V
public static final fun divergentInstance (Lmatchers/content/ContentMatcherBuilder;Lkotlin/jvm/functions/Function1;)V
Expand Down
6 changes: 5 additions & 1 deletion core/content-matcher-test-utils/src/main/kotlin/matchers/content/ContentMatchersDsl.kt
View file
Expand Up @@ -91,6 +91,10 @@ fun ContentMatcherBuilder<*>.platformHinted(block: ContentMatcherBuilder<Content

fun ContentMatcherBuilder<*>.list(block: ContentMatcherBuilder<ContentList>.() -> Unit) = composite(block)

fun ContentMatcherBuilder<*>.codeBlock(block: ContentMatcherBuilder<ContentCodeBlock>.() -> Unit) = composite(block)

fun ContentMatcherBuilder<*>.codeInline(block: ContentMatcherBuilder<ContentCodeInline>.() -> Unit) = composite(block)

fun ContentMatcherBuilder<*>.caption(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) = composite<ContentGroup> {
block()
check { assertThat(this::style).contains(ContentStyle.Caption) }
Expand All @@ -117,4 +121,4 @@ fun ContentMatcherBuilder<ContentDivergentInstance>.divergent(block: ContentMatc
composite(block)

fun ContentMatcherBuilder<ContentDivergentInstance>.after(block: ContentMatcherBuilder<ContentComposite>.() -> Unit) =
composite(block)
composite(block)
9 changes: 7 additions & 2 deletions core/src/main/kotlin/pages/ContentNodes.kt
View file
Expand Up @@ -333,7 +333,12 @@ enum class ContentKind : Kind {
Symbol,

Comment, Constructors, Functions, Parameters, Properties, Classlikes, Packages, Sample, Main, BriefComment,
Empty, Source, TypeAliases, Cover, Inheritors, SourceSetDependentHint, Extensions, Annotations;
Empty, Source, TypeAliases, Cover, Inheritors, SourceSetDependentHint, Extensions, Annotations,

/**
* Deprecation details block with related information such as message/replaceWith/level.
*/
Deprecation;

companion object {
private val platformTagged =
Expand Down Expand Up @@ -388,7 +393,7 @@ enum class TextStyle : Style {

enum class ContentStyle : Style {
RowTitle, TabbedContent, WithExtraAttributes, RunnableSample, InDocumentationAnchor, Caption,
Wrapped, Indented, KDocTag
Wrapped, Indented, KDocTag, Footnote
}

enum class ListStyle : Style {
Expand Down
18 changes: 14 additions & 4 deletions plugins/base/api/base.api
View file
Expand Up @@ -403,20 +403,23 @@ public abstract class org/jetbrains/dokka/base/renderers/html/NavigationDataProv
}

public final class org/jetbrains/dokka/base/renderers/html/NavigationNode : org/jetbrains/dokka/model/WithChildren {
public fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;Ljava/util/List;)V
public fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;Ljava/util/Set;Ljava/util/List;)V
public synthetic fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;Ljava/util/Set;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Ljava/lang/String;
public final fun component2 ()Lorg/jetbrains/dokka/links/DRI;
public final fun component3 ()Ljava/util/Set;
public final fun component4 ()Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;
public final fun component5 ()Ljava/util/List;
public final fun copy (Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;Ljava/util/List;)Lorg/jetbrains/dokka/base/renderers/html/NavigationNode;
public static synthetic fun copy$default (Lorg/jetbrains/dokka/base/renderers/html/NavigationNode;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;Ljava/util/List;ILjava/lang/Object;)Lorg/jetbrains/dokka/base/renderers/html/NavigationNode;
public final fun component5 ()Ljava/util/Set;
public final fun component6 ()Ljava/util/List;
public final fun copy (Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;Ljava/util/Set;Ljava/util/List;)Lorg/jetbrains/dokka/base/renderers/html/NavigationNode;
public static synthetic fun copy$default (Lorg/jetbrains/dokka/base/renderers/html/NavigationNode;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;Ljava/util/Set;Ljava/util/List;ILjava/lang/Object;)Lorg/jetbrains/dokka/base/renderers/html/NavigationNode;
public fun equals (Ljava/lang/Object;)Z
public fun getChildren ()Ljava/util/List;
public final fun getDri ()Lorg/jetbrains/dokka/links/DRI;
public final fun getIcon ()Lorg/jetbrains/dokka/base/renderers/html/NavigationNodeIcon;
public final fun getName ()Ljava/lang/String;
public final fun getSourceSets ()Ljava/util/Set;
public final fun getStyles ()Ljava/util/Set;
public fun hashCode ()I
public fun toString ()Ljava/lang/String;
}
Expand Down Expand Up @@ -909,6 +912,7 @@ public abstract class org/jetbrains/dokka/base/signatures/AtStrategy {

public abstract interface class org/jetbrains/dokka/base/signatures/JvmSignatureUtils {
public abstract fun annotations (Lorg/jetbrains/dokka/model/DProperty;)Ljava/util/Map;
public abstract fun annotations (Lorg/jetbrains/dokka/model/Documentable;)Ljava/util/Map;
public abstract fun annotations (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Ljava/util/Map;
public abstract fun annotationsBlock (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;)V
public abstract fun annotationsBlockWithIgnored (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;Ljava/util/Set;Lorg/jetbrains/dokka/base/signatures/AtStrategy;Lkotlin/Pair;Ljava/lang/String;)V
Expand All @@ -925,6 +929,7 @@ public abstract interface class org/jetbrains/dokka/base/signatures/JvmSignature

public final class org/jetbrains/dokka/base/signatures/JvmSignatureUtils$DefaultImpls {
public static fun annotations (Lorg/jetbrains/dokka/base/signatures/JvmSignatureUtils;Lorg/jetbrains/dokka/model/DProperty;)Ljava/util/Map;
public static fun annotations (Lorg/jetbrains/dokka/base/signatures/JvmSignatureUtils;Lorg/jetbrains/dokka/model/Documentable;)Ljava/util/Map;
public static fun annotations (Lorg/jetbrains/dokka/base/signatures/JvmSignatureUtils;Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Ljava/util/Map;
public static fun annotationsBlockWithIgnored (Lorg/jetbrains/dokka/base/signatures/JvmSignatureUtils;Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;Ljava/util/Set;Lorg/jetbrains/dokka/base/signatures/AtStrategy;Lkotlin/Pair;Ljava/lang/String;)V
public static fun annotationsInlineWithIgnored (Lorg/jetbrains/dokka/base/signatures/JvmSignatureUtils;Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;Ljava/util/Set;Lorg/jetbrains/dokka/base/signatures/AtStrategy;Lkotlin/Pair;Ljava/lang/String;)V
Expand All @@ -940,6 +945,7 @@ public final class org/jetbrains/dokka/base/signatures/KotlinSignatureProvider :
public fun <init> (Lorg/jetbrains/dokka/base/transformers/pages/comments/CommentsToContentConverter;Lorg/jetbrains/dokka/utilities/DokkaLogger;)V
public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
public fun annotations (Lorg/jetbrains/dokka/model/DProperty;)Ljava/util/Map;
public fun annotations (Lorg/jetbrains/dokka/model/Documentable;)Ljava/util/Map;
public fun annotations (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Ljava/util/Map;
public fun annotationsBlock (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;)V
public fun annotationsBlockWithIgnored (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;Ljava/util/Set;Lorg/jetbrains/dokka/base/signatures/AtStrategy;Lkotlin/Pair;Ljava/lang/String;)V
Expand All @@ -958,6 +964,7 @@ public final class org/jetbrains/dokka/base/signatures/KotlinSignatureProvider :
public final class org/jetbrains/dokka/base/signatures/KotlinSignatureUtils : org/jetbrains/dokka/base/signatures/JvmSignatureUtils {
public static final field INSTANCE Lorg/jetbrains/dokka/base/signatures/KotlinSignatureUtils;
public fun annotations (Lorg/jetbrains/dokka/model/DProperty;)Ljava/util/Map;
public fun annotations (Lorg/jetbrains/dokka/model/Documentable;)Ljava/util/Map;
public fun annotations (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Ljava/util/Map;
public fun annotationsBlock (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;)V
public fun annotationsBlockWithIgnored (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;Ljava/util/Set;Lorg/jetbrains/dokka/base/signatures/AtStrategy;Lkotlin/Pair;Ljava/lang/String;)V
Expand Down Expand Up @@ -1266,6 +1273,7 @@ public final class org/jetbrains/dokka/base/transformers/documentables/Suppresse

public final class org/jetbrains/dokka/base/transformers/documentables/UtilsKt {
public static final fun getDeprecatedAnnotation (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Lorg/jetbrains/dokka/model/Annotations$Annotation;
public static final fun isDeprecated (Lorg/jetbrains/dokka/model/Annotations$Annotation;)Z
public static final fun isDeprecated (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Z
public static final fun isException (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Z
}
Expand Down Expand Up @@ -1519,6 +1527,8 @@ public class org/jetbrains/dokka/base/translators/documentables/PageContentBuild
public final fun block (Ljava/lang/String;ILorg/jetbrains/dokka/pages/Kind;Ljava/lang/Iterable;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ZZLjava/util/List;ZLkotlin/jvm/functions/Function2;)V
public static synthetic fun block$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/lang/String;ILorg/jetbrains/dokka/pages/Kind;Ljava/lang/Iterable;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ZZLjava/util/List;ZLkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
public final fun booleanLiteral (Z)V
public final fun breakLine (Ljava/util/Set;)V
public static synthetic fun breakLine$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/util/Set;ILjava/lang/Object;)V
public final fun build (Ljava/util/Set;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Lorg/jetbrains/dokka/pages/ContentGroup;
public final fun buildGroup (Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/pages/ContentGroup;
public static synthetic fun buildGroup$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lorg/jetbrains/dokka/pages/ContentGroup;
Expand Down
3 changes: 3 additions & 0 deletions plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
View file
Expand Up @@ -95,6 +95,7 @@ open class HtmlRenderer(
childrenCallback()
}
node.hasStyle(ContentStyle.KDocTag) -> span("kdoc-tag") { childrenCallback() }
node.hasStyle(ContentStyle.Footnote) -> div("footnote") { childrenCallback() }
node.hasStyle(TextStyle.BreakableAfter) -> {
span { childrenCallback() }
wbr { }
Expand Down Expand Up @@ -124,10 +125,12 @@ open class HtmlRenderer(
node.dci.kind == ContentKind.Cover -> div("cover $additionalClasses") { //TODO this can be removed
childrenCallback()
}
node.dci.kind == ContentKind.Deprecation -> div("deprecation-content") { childrenCallback() }
node.hasStyle(TextStyle.Paragraph) -> p(additionalClasses) { childrenCallback() }
node.hasStyle(TextStyle.Block) -> div(additionalClasses) { childrenCallback() }
node.hasStyle(TextStyle.Quotation) -> blockQuote(additionalClasses) { childrenCallback() }
node.hasStyle(TextStyle.FloatingRight) -> span("clearfix") { span("floating-right") { childrenCallback() } }
node.hasStyle(TextStyle.Strikethrough) -> strike { childrenCallback() }
node.isAnchorable -> buildAnchor(
node.anchor!!,
node.anchorLabel!!,
Expand Down
35 changes: 26 additions & 9 deletions plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt
View file
@@ -1,6 +1,8 @@
package org.jetbrains.dokka.base.renderers.html

import org.jetbrains.dokka.base.renderers.sourceSets
import org.jetbrains.dokka.base.signatures.KotlinSignatureUtils.annotations
import org.jetbrains.dokka.base.transformers.documentables.isDeprecated
import org.jetbrains.dokka.base.transformers.documentables.isException
import org.jetbrains.dokka.base.translators.documentables.DocumentableLanguage
import org.jetbrains.dokka.base.translators.documentables.documentableLanguage
Expand All @@ -17,6 +19,7 @@ abstract class NavigationDataProvider {
dri = page.dri.first(),
sourceSets = page.sourceSets(),
icon = chooseNavigationIcon(page),
styles = chooseStyles(page),
children = page.navigableChildren()
)

Expand All @@ -31,8 +34,8 @@ abstract class NavigationDataProvider {
name
}

private fun chooseNavigationIcon(contentPage: ContentPage): NavigationNodeIcon? {
return if (contentPage is WithDocumentables) {
private fun chooseNavigationIcon(contentPage: ContentPage): NavigationNodeIcon? =
if (contentPage is WithDocumentables) {
val documentable = contentPage.documentables.firstOrNull()
val isJava = documentable?.hasAnyJavaSources() ?: false

Expand Down Expand Up @@ -61,27 +64,41 @@ abstract class NavigationDataProvider {
} else {
null
}
}

private fun Documentable.hasAnyJavaSources(): Boolean {
val withSources = this as? WithSources ?: return false
return this.sourceSets.any { withSources.documentableLanguage(it) == DocumentableLanguage.JAVA }
}

private fun DClass.isAbstract(): Boolean {
return modifier.values.all { it is KotlinModifier.Abstract || it is JavaModifier.Abstract }
private fun DClass.isAbstract() =
modifier.values.all { it is KotlinModifier.Abstract || it is JavaModifier.Abstract }

private fun chooseStyles(page: ContentPage): Set<Style> =
if (page.containsOnlyDeprecatedDocumentables()) setOf(TextStyle.Strikethrough) else emptySet()

private fun ContentPage.containsOnlyDeprecatedDocumentables(): Boolean {
if (this !is WithDocumentables) {
return false
}
return this.documentables.isNotEmpty() && this.documentables.all { it.isDeprecatedForAllSourceSets() }
}

private fun Documentable.isDeprecatedForAllSourceSets(): Boolean {
val sourceSetAnnotations = this.annotations()
return sourceSetAnnotations.isNotEmpty() && sourceSetAnnotations.all { (_, annotations) ->
annotations.any { it.isDeprecated() }
}
}

private fun ContentPage.navigableChildren(): List<NavigationNode> {
return if (this is ClasslikePage) {
return this.navigableChildren()
private fun ContentPage.navigableChildren() =
if (this is ClasslikePage) {
this.navigableChildren()
} else {
children
.filterIsInstance<ContentPage>()
.map { visit(it) }
.sortedBy { it.name.toLowerCase() }
}
}

private fun ClasslikePage.navigableChildren(): List<NavigationNode> {
// Classlikes should only have other classlikes as navigable children
Expand Down
17 changes: 14 additions & 3 deletions plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt
View file
Expand Up @@ -57,24 +57,35 @@ class NavigationPage(
span("nav-link-grid") {
span("nav-link-child ${node.icon?.style()}")
span("nav-link-child") {
buildBreakableText(node.name)
nodeText(node)
}
}
} else {
buildBreakableText(node.name)
nodeText(node)
}
}
}
node.children.withIndex().forEach { (n, p) -> visit(p, "$navId-$n", renderer) }
}
}

private fun FlowContent.nodeText(node: NavigationNode) {
if (node.styles.contains(TextStyle.Strikethrough)) {
strike {
buildBreakableText(node.name)
}
} else {
buildBreakableText(node.name)
}
}
}

data class NavigationNode(
val name: String,
val dri: DRI,
val sourceSets: Set<DisplaySourceSet>,
val icon: NavigationNodeIcon?,
val styles: Set<Style> = emptySet(),
override val children: List<NavigationNode>
) : WithChildren<NavigationNode>

Expand Down Expand Up @@ -108,4 +119,4 @@ fun NavigationPage.transform(block: (NavigationNode) -> NavigationNode) =
NavigationPage(root.transform(block), moduleName, context)

fun NavigationNode.transform(block: (NavigationNode) -> NavigationNode) =
run(block).let { NavigationNode(it.name, it.dri, it.sourceSets, it.icon, it.children.map(block)) }
run(block).let { NavigationNode(it.name, it.dri, it.sourceSets, it.icon, it.styles, it.children.map(block)) }

0 comments on commit 50a3323

Please sign in to comment.