Fix DGP/KMP integration, so Dokka can 'see' code from shared source sets in target source sets #3814

adam-enko · 2024-09-19T11:14:36Z

There are 3 main fixes in this PR:

Update determining the Kotlin target for each source set. (See KotlinAdapter#determineKotlinPlatform). Filter out metadata targets (they're not relevant for target determination), and only fall back to KotlinPlatform.Common if necessary.
Correctly resolve Konan dependencies: Use compilation.konanTarget.name instead of compilation.target.name.
Fix fetching the classpath: For Android projects, fetch both jar and android-classes-jar dependencies. For KGP projects, use compileDependencyFiles.

The remaining changes are to support these fixes:

Add functional test to verify that Dokka can correctly generate docs when 'leaf' source sets (e.g. linuxX64) reference 'branch' source sets (e.g. commonMain, nativeMain).
Update DGPv2 AGP integration test data.
Create a factory for creating DokkaSourceSetSpecs, which means DGP can consistently use convention() to set default values.
Add/update KDoc.

Should fix KT-70857

…ndents

…ndents # Conflicts: # dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/uriUtils.kt

- Filter out legacy KMP metadata compilations (they were retained to support Dokka v1). - Fetch both `jar` and `android-classes-jar` from AGP (probably not necessary, but why not?) - Only use `compilation.compileDependencyFiles` in non-AGP projects. - Add more docs

…ntion set in KotlinAdapter

- implement new JUnit extension to help set up and re-run DGP integration tests with different versions

…ses, tidy Android projects, fix suppress/analysisPlatform defaults.

`fileTree.kt` contains a utility for logging pretty file trees, which is useful in providing human-readable context for test failures. This PR updates the utility to only use NIO Path, rather than the older `java.io.File`. This change was split off from #3814 to make the PR smaller

…ndents # Conflicts: # .gitattributes # build.gradle.kts # dokka-integration-tests/gradle/build.gradle.kts # dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/DokkaGenerateTask.kt # dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleTestKitUtils.kt # dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/fileTree.kt

…/feat/KT-70336/pass-common-src-to-dependents

…ndents

…ndents # Conflicts: # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/index.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/navigation.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/org.dokka.it.android.kmp.core/-menu-item/-menu-item.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/org.dokka.it.android.kmp.core/-menu-item/image-vector.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/org.dokka.it.android.kmp.core/-menu-item/index.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/org.dokka.it.android.kmp.core/-menu-item/is-important.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/org.dokka.it.android.kmp.core/-menu-item/label.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/org.dokka.it.android.kmp.core/-menu-item/on-click.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/core/org.dokka.it.android.kmp.core/index.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/material3/index.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/material3/navigation.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/material3/org.dokka.it.android.kmp.material3/-top-app-bar-action.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/material3/org.dokka.it.android.kmp.material3/index.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/navigation.html # dokka-integration-tests/gradle/projects/it-android-compose/expectedData/html/scripts/pages.json # dokka-integration-tests/gradle/projects/it-android/expectedData/html/it-android-0/it.android/-integration-test-activity/index.html # dokka-integration-tests/gradle/projects/it-android/expectedData/html/it-android-0/it.android/index.html # dokka-integration-tests/gradle/projects/it-android/expectedData/html/it-android-0/package-list # dokka-integration-tests/gradle/projects/it-android/expectedData/html/scripts/pages.json # dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/junit/DokkaGradlePluginTestExtension.kt # dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/junit/GradleTestProjectInitializer.kt # dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/junit/TestedVersions.kt # dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/junit/testTags.kt # dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/utils/SemVer.kt # dokka-integration-tests/gradle/src/test/kotlin/AndroidComposeIT.kt # dokka-integration-tests/gradle/src/test/kotlin/AndroidProjectIT.kt # dokka-integration-tests/gradle/src/testTemplateProjectAndroid/kotlin/Android0GradleIntegrationTest.kt # dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/DokkaGenerateTask.kt

- Filter out metadata compilations when determining the source set target. - Remove KotlinPlatform warning - it's always triggered for commonMain. - Fetch _all_ dependent source sets, including transitives.

whyoleg

Nice!
Changes to defaults are looks logical for me, only the test placement worries me :)

whyoleg · 2024-11-22T09:15:39Z

dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/KotlinAdapter.kt

+                        if (compilation.target.platformType == androidJvm) {
+                            attributes { artifactType(artifactType) }
+
+                            // Setting lenient=true is not ideal, because it might hide problems.


just curious: is it possible to somehow log those problems in case of lenient=true or are they just silently ignored? just for troubleshooting?

whyoleg · 2024-11-22T09:17:18Z

dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/kotestFiles.kt

@@ -91,7 +91,7 @@ private fun describeFileDifferences(
                    /* revisedFileName = */ actualFile.relativeTo(actualDir).invariantSeparatorsPathString,
                    /* originalLines = */ expectedLines,
                    /* patch = */ patch,
-                    /* contextSize = */ 3,
+                    /* contextSize = */ 0,


is it an expected change?

whyoleg · 2024-11-22T09:19:44Z

...ers/dokka-gradle-plugin/src/testFunctional/kotlin/KmpCommonSourceSharedWithDependentsTest.kt

+import kotlin.io.path.walk
+
+@Ignored("KMP: References is not linked if they are in shared code and there is an intermediate level between them https://github.com/Kotlin/dokka/issues/3382")
+class KmpCommonSourceSharedWithDependentsTest : FunSpec({


I believe this test should be placed into dokka-integration-tests so that we will be able to check it with different Kotlin versions.
In my understanding, functional tests in DGPv2 are more about plugin behavior while this test is more about overall Dokka behavior and so should be in IT

I would probably except here a test which checks that we set correct defaults for DokkaSourceSetSpec platform, dependsOn and etc

Fix common source sets not propogated

ecc43a5

adam-enko added the runner: Gradle plugin An issue/PR related to Dokka's Gradle plugin label Sep 19, 2024

adam-enko self-assigned this Sep 19, 2024

adam-enko added 19 commits September 23, 2024 09:01

Add some kdoc

fc6319b

refine test

1482ecf

Fix fetching platform sources

1522d04

Merge branch 'master' into adam/feat/KT-70336/pass-common-src-to-depe…

e45e4d9

…ndents

Merge branch 'master' into adam/feat/KT-70336/pass-common-src-to-depe…

c41a249

…ndents

wip

a639d51

Merge branch 'master' into adam/feat/KT-70336/pass-common-src-to-depe…

148f821

…ndents # Conflicts: # dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/uriUtils.kt

Sort DokkaSourceSets (helps with debugging)

ad6a532

Fix convention for DokkaSourceSetSpec.suppress

169a859

Fix convention for DokkaSourceSetSpec.suppress

0c8605d

Add 'Dokka' to warn message

586d603

remove analysis platform convention, otherwise it overrides the conve…

f80f5b4

…ntion set in KotlinAdapter

Deprecate unused KotlinPlatform.DEFAULT

ead23da

IT Android with DGPv2

a3919ed

- implement new JUnit extension to help set up and re-run DGP integration tests with different versions

test Android Compose project

22cd3d5

Tidy DokkaGradlePluginTestExtension, split up file into separate clas…

e895ca1

…ses, tidy Android projects, fix suppress/analysisPlatform defaults.

Tidy GradleTestProjectInitializer

651cdf8

run tests with Java 17

91ee7d0

whyoleg mentioned this pull request Oct 31, 2024

[Dokka 2] References from a module description to module's classes are no longer rendered as links #3890

Open

adam-enko mentioned this pull request Oct 31, 2024

Update fileTree test util to only use NIO Path #3892

Merged

adam-enko added 4 commits November 4, 2024 14:55

tidy after merge

7fe86c9

add project path to log message

c65a390

remove unused code... (maybe use it again in the future?)

718cc3a

adam-enko added 5 commits November 12, 2024 11:29

update expected data

383f029

fix import

5053890

Merge branch 'adam/feat/KT-70336/android-integration-tests' into adam…

fc38971

…/feat/KT-70336/pass-common-src-to-dependents

Merge branch 'master' into adam/feat/KT-70336/pass-common-src-to-depe…

16344f7

…ndents

update clue message

4e789df

antohaby self-requested a review November 18, 2024 14:09

Base automatically changed from adam/feat/KT-70336/android-integration-tests to master November 20, 2024 09:45

adam-enko added 15 commits November 20, 2024 10:49

reduce diff output for shouldBeADirectoryWithSameContentAs failure

82cfac1

un-ignore AndroidProject HTML test for AGP 8

f944fd4

update expected HTML for Android projects

c1b3520

fix test rootProject name

80b7a26

reduce output of shouldBeADirectoryWithSameContentAs assertion

4faf753

update expected data for Android projects

4f20f11

revert truncation of diff lines

5c34de3

try building project first...

a1a5fce

tidy kdoc

71e12e3

Add kdoc to dokkaSourceSetSpecFactory

d5d394f

Improve KmpCommonSourceSharedWithDependentsTest

35f960e

Update KotlinAdapter:

6f299d5

- Filter out metadata compilations when determining the source set target. - Remove KotlinPlatform warning - it's always triggered for commonMain. - Fetch _all_ dependent source sets, including transitives.

copy old comment for DSS.suppress

31d521c

revert adding arg name

e62424b

adam-enko changed the title ~~Fix common source sets not propogated~~ Fix DGP/KMP integration, so Dokka can 'see' code from shared source sets in target source sets Nov 21, 2024

adam-enko added 3 commits November 21, 2024 15:07

extract KotlinPlatform computation to a function

36eb7d7

revert depending on all transitive source sets

aca1c58

disable KmpCommonSourceSharedWithDependentsTest, because of #3382

c1d803c

adam-enko requested a review from whyoleg November 21, 2024 18:54

adam-enko added this to the Dokka 2.0.0 milestone Nov 21, 2024

adam-enko marked this pull request as ready for review November 21, 2024 18:55

whyoleg approved these changes Nov 22, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix DGP/KMP integration, so Dokka can 'see' code from shared source sets in target source sets #3814

Fix DGP/KMP integration, so Dokka can 'see' code from shared source sets in target source sets #3814

adam-enko commented Sep 19, 2024 •

edited

Loading

whyoleg left a comment

whyoleg Nov 22, 2024

whyoleg Nov 22, 2024

whyoleg Nov 22, 2024

whyoleg Nov 22, 2024

Fix DGP/KMP integration, so Dokka can 'see' code from shared source sets in target source sets #3814

Are you sure you want to change the base?

Fix DGP/KMP integration, so Dokka can 'see' code from shared source sets in target source sets #3814

Conversation

adam-enko commented Sep 19, 2024 • edited Loading

whyoleg left a comment

Choose a reason for hiding this comment

whyoleg Nov 22, 2024

Choose a reason for hiding this comment

whyoleg Nov 22, 2024

Choose a reason for hiding this comment

whyoleg Nov 22, 2024

Choose a reason for hiding this comment

whyoleg Nov 22, 2024

Choose a reason for hiding this comment

adam-enko commented Sep 19, 2024 •

edited

Loading