Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enable explicit API mode #3139

Merged
merged 2 commits into from
Aug 31, 2023
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
package org.jetbrains.conventions

import org.jetbrains.configureDokkaVersion
import org.jetbrains.kotlin.gradle.dsl.ExplicitApiMode
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
Expand All @@ -14,25 +15,44 @@ plugins {

configureDokkaVersion()

val projectsWithoutOptInDependency = setOf(
":integration-tests", ":integration-tests:gradle", ":integration-tests:maven", ":integration-tests:cli")
kotlin {
explicitApi = ExplicitApiMode.Strict
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If explicitApi was set in tasks.withType<KotlinCompile>(), it would be applied to the test sources as well, which we don't want. But setting it in kotlin {} fixes it, so I did that and moved other compiler arguments into it as well.


compilerOptions {
allWarningsAsErrors.set(true)
languageVersion.set(dokkaBuild.kotlinLanguageLevel)
apiVersion.set(dokkaBuild.kotlinLanguageLevel)

freeCompilerArgs.addAll(
listOf(
// need 1.4 support, otherwise there might be problems
// with Gradle 6.x (it's bundling Kotlin 1.4)
"-Xsuppress-version-warnings",
"-Xjsr305=strict",
"-Xskip-metadata-version-check",
)
)
}
}

val projectsWithoutInternalDokkaApiUsage = setOf(
":integration-tests",
":integration-tests:gradle",
":integration-tests:maven",
":integration-tests:cli"
)

tasks.withType<KotlinCompile>().configureEach {
// By path because Dokka has multiple projects with the same name (i.e. 'cli')
if (project.path in projectsWithoutOptInDependency) return@configureEach
if (project.path in projectsWithoutInternalDokkaApiUsage) {
return@configureEach
}
compilerOptions {
freeCompilerArgs.addAll(
listOf(
"-opt-in=kotlin.RequiresOptIn",
"-opt-in=org.jetbrains.dokka.InternalDokkaApi",
"-Xjsr305=strict",
"-Xskip-metadata-version-check",
// need 1.4 support, otherwise there might be problems with Gradle 6.x (it's bundling Kotlin 1.4)
"-Xsuppress-version-warnings",
)
)
allWarningsAsErrors.set(true)
languageVersion.set(dokkaBuild.kotlinLanguageLevel)
apiVersion.set(dokkaBuild.kotlinLanguageLevel)
}
}
15 changes: 7 additions & 8 deletions core/api/core.api
Original file line number Diff line number Diff line change
Expand Up @@ -658,7 +658,7 @@ public final class org/jetbrains/dokka/model/ActualTypealias : org/jetbrains/dok

public final class org/jetbrains/dokka/model/ActualTypealias$Companion : org/jetbrains/dokka/model/properties/ExtraProperty$Key {
public synthetic fun mergeStrategyFor (Ljava/lang/Object;Ljava/lang/Object;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/ActualTypealias;Lorg/jetbrains/dokka/model/ActualTypealias;)Lorg/jetbrains/dokka/model/properties/MergeStrategy$Fail;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/ActualTypealias;Lorg/jetbrains/dokka/model/ActualTypealias;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
}

public final class org/jetbrains/dokka/model/AdditionalExtrasKt {
Expand Down Expand Up @@ -817,7 +817,7 @@ public final class org/jetbrains/dokka/model/CheckedExceptions : org/jetbrains/d

public final class org/jetbrains/dokka/model/CheckedExceptions$Companion : org/jetbrains/dokka/model/properties/ExtraProperty$Key {
public synthetic fun mergeStrategyFor (Ljava/lang/Object;Ljava/lang/Object;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/CheckedExceptions;Lorg/jetbrains/dokka/model/CheckedExceptions;)Lorg/jetbrains/dokka/model/properties/MergeStrategy$Replace;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/CheckedExceptions;Lorg/jetbrains/dokka/model/CheckedExceptions;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
}

public abstract interface class org/jetbrains/dokka/model/ClassKind {
Expand Down Expand Up @@ -1505,7 +1505,7 @@ public final class org/jetbrains/dokka/model/ExceptionInSupertypes : org/jetbrai

public final class org/jetbrains/dokka/model/ExceptionInSupertypes$Companion : org/jetbrains/dokka/model/properties/ExtraProperty$Key {
public synthetic fun mergeStrategyFor (Ljava/lang/Object;Ljava/lang/Object;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/ExceptionInSupertypes;Lorg/jetbrains/dokka/model/ExceptionInSupertypes;)Lorg/jetbrains/dokka/model/properties/MergeStrategy$Replace;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/ExceptionInSupertypes;Lorg/jetbrains/dokka/model/ExceptionInSupertypes;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
}

public abstract interface class org/jetbrains/dokka/model/Expression {
Expand Down Expand Up @@ -1707,7 +1707,7 @@ public final class org/jetbrains/dokka/model/ImplementedInterfaces : org/jetbrai

public final class org/jetbrains/dokka/model/ImplementedInterfaces$Companion : org/jetbrains/dokka/model/properties/ExtraProperty$Key {
public synthetic fun mergeStrategyFor (Ljava/lang/Object;Ljava/lang/Object;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/ImplementedInterfaces;Lorg/jetbrains/dokka/model/ImplementedInterfaces;)Lorg/jetbrains/dokka/model/properties/MergeStrategy$Replace;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/ImplementedInterfaces;Lorg/jetbrains/dokka/model/ImplementedInterfaces;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
}

public final class org/jetbrains/dokka/model/InheritedMember : org/jetbrains/dokka/model/properties/ExtraProperty {
Expand All @@ -1726,7 +1726,7 @@ public final class org/jetbrains/dokka/model/InheritedMember : org/jetbrains/dok

public final class org/jetbrains/dokka/model/InheritedMember$Companion : org/jetbrains/dokka/model/properties/ExtraProperty$Key {
public synthetic fun mergeStrategyFor (Ljava/lang/Object;Ljava/lang/Object;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/InheritedMember;Lorg/jetbrains/dokka/model/InheritedMember;)Lorg/jetbrains/dokka/model/properties/MergeStrategy$Replace;
public fun mergeStrategyFor (Lorg/jetbrains/dokka/model/InheritedMember;Lorg/jetbrains/dokka/model/InheritedMember;)Lorg/jetbrains/dokka/model/properties/MergeStrategy;
}

public final class org/jetbrains/dokka/model/IntValue : org/jetbrains/dokka/model/LiteralValue {
Expand Down Expand Up @@ -4103,8 +4103,7 @@ public final class org/jetbrains/dokka/pages/MultimoduleRootPageNode : org/jetbr
public fun getName ()Ljava/lang/String;
public synthetic fun modified (Ljava/lang/String;Ljava/util/List;)Lorg/jetbrains/dokka/pages/PageNode;
public fun modified (Ljava/lang/String;Ljava/util/List;)Lorg/jetbrains/dokka/pages/RootPageNode;
public synthetic fun modified (Ljava/lang/String;Lorg/jetbrains/dokka/pages/ContentNode;Ljava/util/Set;Ljava/util/List;Ljava/util/List;)Lorg/jetbrains/dokka/pages/ContentPage;
public fun modified (Ljava/lang/String;Lorg/jetbrains/dokka/pages/ContentNode;Ljava/util/Set;Ljava/util/List;Ljava/util/List;)Lorg/jetbrains/dokka/pages/MultimoduleRootPageNode;
public fun modified (Ljava/lang/String;Lorg/jetbrains/dokka/pages/ContentNode;Ljava/util/Set;Ljava/util/List;Ljava/util/List;)Lorg/jetbrains/dokka/pages/ContentPage;
}

public final class org/jetbrains/dokka/pages/MultimoduleTable : org/jetbrains/dokka/pages/Style {
Expand Down Expand Up @@ -4166,7 +4165,7 @@ public final class org/jetbrains/dokka/pages/PlatformHintedContent : org/jetbrai
public synthetic fun transformChildren (Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/pages/ContentComposite;
public fun transformChildren (Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/pages/PlatformHintedContent;
public synthetic fun withNewExtras (Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Ljava/lang/Object;
public fun withNewExtras (Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Ljava/lang/Void;
public fun withNewExtras (Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Lorg/jetbrains/dokka/pages/ContentNode;
public synthetic fun withSourceSets (Ljava/util/Set;)Lorg/jetbrains/dokka/pages/ContentNode;
public fun withSourceSets (Ljava/util/Set;)Lorg/jetbrains/dokka/pages/PlatformHintedContent;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import kotlin.test.assertEquals
import kotlin.test.asserter

// entry point:
fun ContentNode.assertNode(block: ContentMatcherBuilder<ContentComposite>.() -> Unit) {
public fun ContentNode.assertNode(block: ContentMatcherBuilder<ContentComposite>.() -> Unit) {
val matcher = ContentMatcherBuilder(ContentComposite::class).apply(block).build()
try {
matcher.tryMatch(this)
Expand All @@ -24,123 +24,161 @@ fun ContentNode.assertNode(block: ContentMatcherBuilder<ContentComposite>.() ->

// DSL:
@DslMarker
annotation class ContentMatchersDsl
public annotation class ContentMatchersDsl

@ContentMatchersDsl
class ContentMatcherBuilder<T : ContentComposite> @PublishedApi internal constructor(private val kclass: KClass<T>) {
public class ContentMatcherBuilder<T : ContentComposite> @PublishedApi internal constructor(private val kclass: KClass<T>) {
@PublishedApi
internal val children = mutableListOf<MatcherElement>()
internal val children: MutableList<MatcherElement> = mutableListOf()
internal val assertions = mutableListOf<T.() -> Unit>()

fun build() = CompositeMatcher(kclass, childrenOrSkip()) { assertions.forEach { it() } }
public fun build(): CompositeMatcher<T> = CompositeMatcher(kclass, childrenOrSkip()) { assertions.forEach { it() } }

// part of DSL that cannot be defined as an extension
operator fun String.unaryPlus() {
public operator fun String.unaryPlus() {
children += TextMatcher(this)
}

private fun childrenOrSkip() = if (children.isEmpty() && assertions.isNotEmpty()) listOf(Anything) else children
}

fun <T : ContentComposite> ContentMatcherBuilder<T>.check(assertion: T.() -> Unit) {
public fun <T : ContentComposite> ContentMatcherBuilder<T>.check(assertion: T.() -> Unit) {
assertions += assertion
}

private val ContentComposite.extractedText
get() = withDescendants().filterIsInstance<ContentText>().joinToString(separator = "") { it.text }

fun <T : ContentComposite> ContentMatcherBuilder<T>.hasExactText(expected: String) {
public fun <T : ContentComposite> ContentMatcherBuilder<T>.hasExactText(expected: String) {
assertions += {
assertEquals(expected, this.extractedText)
}
}

inline fun <reified S : ContentComposite> ContentMatcherBuilder<*>.composite(
public inline fun <reified S : ContentComposite> ContentMatcherBuilder<*>.composite(
block: ContentMatcherBuilder<S>.() -> Unit
) {
children += ContentMatcherBuilder(S::class).apply(block).build()
}

inline fun <reified S : ContentNode> ContentMatcherBuilder<*>.node(noinline assertions: S.() -> Unit = {}) {
public inline fun <reified S : ContentNode> ContentMatcherBuilder<*>.node(noinline assertions: S.() -> Unit = {}) {
children += NodeMatcher(S::class, assertions)
}

fun ContentMatcherBuilder<*>.skipAllNotMatching() {
public fun ContentMatcherBuilder<*>.skipAllNotMatching() {
children += Anything
}


// Convenience functions:
fun ContentMatcherBuilder<*>.group(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) = composite(block)
public fun ContentMatcherBuilder<*>.group(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) {
composite(block)
}

fun ContentMatcherBuilder<*>.tabbedGroup(
public fun ContentMatcherBuilder<*>.tabbedGroup(
block: ContentMatcherBuilder<ContentGroup>.() -> Unit
) = composite<ContentGroup> {
block()
check { assertContains(this.style, ContentStyle.TabbedContent) }
) {
composite<ContentGroup> {
block()
check { assertContains(this.style, ContentStyle.TabbedContent) }
}
}

fun ContentMatcherBuilder<*>.tab(
public fun ContentMatcherBuilder<*>.tab(
tabbedContentType: TabbedContentType, block: ContentMatcherBuilder<ContentGroup>.() -> Unit
) = composite<ContentGroup> {
block()
check {
assertEquals(tabbedContentType, this.extra[TabbedContentTypeExtra]?.value)
) {
composite<ContentGroup> {
block()
check {
assertEquals(tabbedContentType, this.extra[TabbedContentTypeExtra]?.value)
}
}
}

fun ContentMatcherBuilder<*>.header(expectedLevel: Int? = null, block: ContentMatcherBuilder<ContentHeader>.() -> Unit) =
public fun ContentMatcherBuilder<*>.header(expectedLevel: Int? = null, block: ContentMatcherBuilder<ContentHeader>.() -> Unit) {
composite<ContentHeader> {
block()
check { if (expectedLevel != null) assertEquals(expectedLevel, this.level) }
}
}

fun ContentMatcherBuilder<*>.p(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) =
public fun ContentMatcherBuilder<*>.p(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) {
composite<ContentGroup> {
block()
check { assertContains(this.style, TextStyle.Paragraph) }
}
}

fun ContentMatcherBuilder<*>.link(block: ContentMatcherBuilder<ContentLink>.() -> Unit) = composite(block)
public fun ContentMatcherBuilder<*>.link(block: ContentMatcherBuilder<ContentLink>.() -> Unit) {
composite(block)
}

fun ContentMatcherBuilder<*>.table(block: ContentMatcherBuilder<ContentTable>.() -> Unit) = composite(block)
public fun ContentMatcherBuilder<*>.table(block: ContentMatcherBuilder<ContentTable>.() -> Unit) {
composite(block)
}

fun ContentMatcherBuilder<*>.platformHinted(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) =
public fun ContentMatcherBuilder<*>.platformHinted(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) {
composite<PlatformHintedContent> { group(block) }
}

fun ContentMatcherBuilder<*>.list(block: ContentMatcherBuilder<ContentList>.() -> Unit) = composite(block)
public fun ContentMatcherBuilder<*>.list(block: ContentMatcherBuilder<ContentList>.() -> Unit) {
composite(block)
}
Comment on lines -111 to +126
Copy link
Member Author

@IgnatBeresnev IgnatBeresnev Aug 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of specifying the : Unit return type, I converted void functions to block bodies. Didn't think it would lead to so many changes lines, sorry if it makes it difficult to review :(


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

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

fun ContentMatcherBuilder<*>.caption(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) = composite<ContentGroup> {
block()
check { assertContains(this.style, ContentStyle.Caption) }
public fun ContentMatcherBuilder<*>.caption(block: ContentMatcherBuilder<ContentGroup>.() -> Unit) {
composite<ContentGroup> {
block()
check { assertContains(this.style, ContentStyle.Caption) }
}
}

fun ContentMatcherBuilder<*>.br() = node<ContentBreakLine>()
public fun ContentMatcherBuilder<*>.br() {
node<ContentBreakLine>()
}

fun ContentMatcherBuilder<*>.somewhere(block: ContentMatcherBuilder<*>.() -> Unit) {
public fun ContentMatcherBuilder<*>.somewhere(block: ContentMatcherBuilder<*>.() -> Unit) {
skipAllNotMatching()
block()
skipAllNotMatching()
}

fun ContentMatcherBuilder<*>.divergentGroup(block: ContentMatcherBuilder<ContentDivergentGroup>.() -> Unit) =
public fun ContentMatcherBuilder<*>.divergentGroup(
block: ContentMatcherBuilder<ContentDivergentGroup>.() -> Unit
) {
composite(block)
}

fun ContentMatcherBuilder<ContentDivergentGroup>.divergentInstance(block: ContentMatcherBuilder<ContentDivergentInstance>.() -> Unit) =
public fun ContentMatcherBuilder<ContentDivergentGroup>.divergentInstance(
block: ContentMatcherBuilder<ContentDivergentInstance>.() -> Unit
) {
composite(block)
}

fun ContentMatcherBuilder<ContentDivergentInstance>.before(block: ContentMatcherBuilder<ContentComposite>.() -> Unit) =
public fun ContentMatcherBuilder<ContentDivergentInstance>.before(
block: ContentMatcherBuilder<ContentComposite>.() -> Unit
) {
composite(block)
}

fun ContentMatcherBuilder<ContentDivergentInstance>.divergent(block: ContentMatcherBuilder<ContentComposite>.() -> Unit) =
public fun ContentMatcherBuilder<ContentDivergentInstance>.divergent(
block: ContentMatcherBuilder<ContentComposite>.() -> Unit
) {
composite(block)
}

fun ContentMatcherBuilder<ContentDivergentInstance>.after(block: ContentMatcherBuilder<ContentComposite>.() -> Unit) =
public fun ContentMatcherBuilder<ContentDivergentInstance>.after(
block: ContentMatcherBuilder<ContentComposite>.() -> Unit
) {
composite(block)
}

/*
* TODO replace with kotlin.test.assertContains after migrating to Kotlin language version 1.5+
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,18 @@ import kotlin.reflect.KClass
import kotlin.reflect.full.cast
import kotlin.reflect.full.safeCast

sealed class MatcherElement
public sealed class MatcherElement

class TextMatcher(val text: String) : MatcherElement()
public class TextMatcher(
public val text: String
) : MatcherElement()

open class NodeMatcher<T : ContentNode>(
val kclass: KClass<T>,
val assertions: T.() -> Unit = {}
public open class NodeMatcher<T : ContentNode>(
public val kclass: KClass<T>,
public val assertions: T.() -> Unit = {}
) : MatcherElement() {
open fun tryMatch(node: ContentNode) {

public open fun tryMatch(node: ContentNode) {
kclass.safeCast(node)?.apply {
try {
assertions()
Expand All @@ -37,11 +40,12 @@ open class NodeMatcher<T : ContentNode>(
}
}

class CompositeMatcher<T : ContentComposite>(
public class CompositeMatcher<T : ContentComposite>(
kclass: KClass<T>,
private val children: List<MatcherElement>,
assertions: T.() -> Unit = {}
) : NodeMatcher<T>(kclass, assertions) {

internal val normalizedChildren: List<MatcherElement> by lazy {
children.fold(listOf()) { acc, e ->
when {
Expand All @@ -61,7 +65,7 @@ class CompositeMatcher<T : ContentComposite>(
}
}

object Anything : MatcherElement()
public object Anything : MatcherElement()

private sealed class MatchWalkerState {
abstract fun next(node: ContentNode): MatchWalkerState
Expand Down Expand Up @@ -176,7 +180,7 @@ private fun ContentNode.debugRepresentation() = asPrintableTree { element ->
)
}

data class MatcherError(
public data class MatcherError(
override val message: String,
val anchor: MatcherElement,
val anchorAfter: Boolean = false,
Expand Down
Loading
Loading