Merge "Require KMP projects to use kmpDocs in tip-of-tree" into androidx-main

8 files changed, 62 insertions, 39 deletions

diff --git a/buildSrc/private/src/main/kotlin/androidx/build/checkapi/ApiTasks.kt b/buildSrc/private/src/main/kotlin/androidx/build/checkapi/ApiTasks.kt
index 79c3d60a969..2cb21222825 100644
--- a/buildSrc/private/src/main/kotlin/androidx/build/checkapi/ApiTasks.kt
+++ b/buildSrc/private/src/main/kotlin/androidx/build/checkapi/ApiTasks.kt
@@ -26,6 +26,7 @@ import androidx.build.getSupportRootFolder
 import androidx.build.isWriteVersionedApiFilesEnabled
 import androidx.build.java.JavaCompileInputs
 import androidx.build.metalava.MetalavaTasks
+import androidx.build.multiplatformExtension
 import androidx.build.resources.ResourceTasks
 import androidx.build.stableaidl.setupWithStableAidlPlugin
 import androidx.build.uptodatedness.cacheEvenIfNoOutputs
@@ -156,6 +157,7 @@ fun Project.configureProjectForApiTasks(config: ApiTaskConfig, extension: Androi
                     project.getSupportRootFolder().resolve("docs-tip-of-tree/build.gradle")
                 )
                 task.projectPathProvider.set(path)
+                task.projectIsKmp.set(project.multiplatformExtension != null)
                 task.cacheEvenIfNoOutputs()
             }
             project.addToBuildOnServer(checkDocs)
diff --git a/buildSrc/private/src/main/kotlin/androidx/build/docs/CheckTipOfTreeDocsTask.kt b/buildSrc/private/src/main/kotlin/androidx/build/docs/CheckTipOfTreeDocsTask.kt
index 4304dae7f66..d90569f1c8c 100644
--- a/buildSrc/private/src/main/kotlin/androidx/build/docs/CheckTipOfTreeDocsTask.kt
+++ b/buildSrc/private/src/main/kotlin/androidx/build/docs/CheckTipOfTreeDocsTask.kt
@@ -39,23 +39,44 @@ abstract class CheckTipOfTreeDocsTask : DefaultTask() {
     @get:Input
     abstract val projectPathProvider: Property<String>
 
+    @get:Input
+    abstract val projectIsKmp: Property<Boolean>
+
     @TaskAction
     fun exec() {
+        val projectPath = projectPathProvider.get()
         // Make sure not to allow a partial project path match, e.g. ":activity:activity" shouldn't
         // match ":activity:activity-ktx", both need to be listed separately.
-        val projectPath = projectPathProvider.get()
-        val fullExpectedText = "project(\"$projectPath\")"
-        if (!tipOfTreeBuildFile.asFile.get().readText().contains(fullExpectedText)) {
-            val message = "Project $projectPath not found in docs-tip-of-tree/build.gradle\n\n" +
-                "Use the project creation script (development/project-creator/create_project.py) " +
-                "when setting up a project to make sure all required steps are complete.\n\n" +
-                "The project should be added to docs-tip-of-tree/build.gradle as " +
-                "\'docs(project(\"$projectPath\"))\' (use 'kmpDocs' instead of 'docs' for KMP " +
-                "projects).\n\n" +
-                "If this project should not have published refdocs, first check that the library " +
-                "type listed in its build.gradle file is accurate. If it is, opt out of refdoc " +
-                "generation using \'doNotDocumentReason = \"some reason\"\' in the 'androidx' " +
-                "configuration section (this is not common)."
+        val projectDependency = "project(\"$projectPath\")"
+
+        val isKmp = projectIsKmp.get()
+        val fullExpectedText = if (isKmp) {
+            // Check that KMP projects are listed as KMP
+            "kmpDocs($projectDependency)"
+        } else {
+            // Don't require `docs($projectDependency)` because some projects are present as stubs.
+            projectDependency
+        }
+
+        val fileContents = tipOfTreeBuildFile.asFile.get().readText()
+        if (!fileContents.contains(fullExpectedText)) {
+            // If this is a KMP project, check if it is present but configured as non-KMP
+            val message = if (isKmp && fileContents.contains(projectDependency)) {
+                "KMP project $projectPath needs 'kmpDocs' in docs-tip-of-tree/build.gradle\n\n" +
+                    "Update the entry for $projectPath in docs-tip-of-tree/build.gradle to " +
+                    "'$fullExpectedText'."
+            } else {
+                "Project $projectPath not found in docs-tip-of-tree/build.gradle\n\n" +
+                    "Use the project creation script (development/project-creator/" +
+                    "create_project.py) when setting up a project to make sure all required " +
+                    "steps are complete.\n\n" +
+                    "The project should be added to docs-tip-of-tree/build.gradle as " +
+                    "\'$fullExpectedText\'.\n\n" +
+                    "If this project should not have published refdocs, first check that the " +
+                    "library type listed in its build.gradle file is accurate. If it is, opt out " +
+                    "of refdoc generation using \'doNotDocumentReason = \"some reason\"\' in the " +
+                    "'androidx' configuration section (this is not common)."
+            }
             throw GradleException(message)
         }
     }
diff --git a/development/build_log_simplifier/messages.ignore b/development/build_log_simplifier/messages.ignore
index 799d2bd7398..6294b28ed93 100644
--- a/development/build_log_simplifier/messages.ignore
+++ b/development/build_log_simplifier/messages.ignore
@@ -410,8 +410,8 @@ WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/ItemKeyedD
 WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/ItemKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `requestedLoadSize` in DFunction LoadInitialParams
 WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/ItemKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `key` in DFunction LoadParams
 WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/ItemKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `requestedLoadSize` in DFunction LoadParams
-WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/PageKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `nextPageKey` in DFunction onResult
-WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/PageKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `previousPageKey` in DFunction onResult
+WARN: .*\/unzipped.*\/commonJvmAndroidMain\/androidx\/paging\/PageKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `nextPageKey` in DFunction onResult
+WARN: .*\/unzipped.*\/commonJvmAndroidMain\/androidx\/paging\/PageKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `previousPageKey` in DFunction onResult
 WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/PageKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `placeholdersEnabled` in DFunction LoadInitialParams
 WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/PageKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `requestedLoadSize` in DFunction LoadInitialParams
 WARN: .*\/unzippedJvmSources\/commonJvmAndroidMain\/androidx\/paging\/PageKeyedDataSource\.jvm\.kt:[0-9]+ Missing @param tag for parameter `key` in DFunction LoadParams
diff --git a/docs-tip-of-tree/build.gradle b/docs-tip-of-tree/build.gradle
index 8dfb4b72555..db60af0cbfb 100644
--- a/docs-tip-of-tree/build.gradle
+++ b/docs-tip-of-tree/build.gradle
@@ -58,7 +58,7 @@ dependencies {
     stubs(fileTree(dir: "../camera/camera-extensions-stub", include: ["camera-extensions-stub.jar"]))
     docs(project(":camera:camera-lifecycle"))
     docs(project(":camera:camera-mlkit-vision"))
-    docsWithoutApiSince(project(":camera:camera-testing"))
+    docs(project(":camera:camera-testing"))
     docs(project(":camera:camera-video"))
     docs(project(":camera:camera-view"))
     docs(project(":camera:camera-viewfinder"))
@@ -87,7 +87,7 @@ dependencies {
     samples(project(":compose:material3:material3-adaptive:material3-adaptive-samples"))
     kmpDocs(project(":compose:material3:material3-adaptive-navigation-suite"))
     samples(project(":compose:material3:material3-adaptive-navigation-suite:material3-adaptive-navigation-suite-samples"))
-    docs(project(":compose:material3:material3-common"))
+    kmpDocs(project(":compose:material3:material3-common"))
     samples(project(":compose:material3:material3:material3-samples"))
     kmpDocs(project(":compose:material3:material3-window-size-class"))
     samples(project(":compose:material3:material3-window-size-class:material3-window-size-class-samples"))
@@ -208,7 +208,7 @@ dependencies {
     docs(project(":graphics:graphics-core"))
     samples(project(":graphics:graphics-core:graphics-core-samples"))
     docs(project(":graphics:graphics-path"))
-    docs(project(":graphics:graphics-shapes"))
+    kmpDocs(project(":graphics:graphics-shapes"))
     docs(project(":gridlayout:gridlayout"))
     docs(project(":health:connect:connect-client"))
     samples(project(":health:connect:connect-client-samples"))
@@ -229,7 +229,7 @@ dependencies {
     docs(project(":leanback:leanback-paging"))
     docs(project(":leanback:leanback-preference"))
     docs(project(":leanback:leanback-tab"))
-    docs(project(":lifecycle:lifecycle-common"))
+    kmpDocs(project(":lifecycle:lifecycle-common"))
     docs(project(":lifecycle:lifecycle-common-java8"))
     docs(project(":lifecycle:lifecycle-extensions"))
     docs(project(":lifecycle:lifecycle-livedata"))
@@ -239,7 +239,7 @@ dependencies {
     docs(project(":lifecycle:lifecycle-process"))
     docs(project(":lifecycle:lifecycle-reactivestreams"))
     docs(project(":lifecycle:lifecycle-reactivestreams-ktx"))
-    docs(project(":lifecycle:lifecycle-runtime"))
+    kmpDocs(project(":lifecycle:lifecycle-runtime"))
     docs(project(":lifecycle:lifecycle-runtime-compose"))
     samples(project(":lifecycle:lifecycle-runtime-compose:lifecycle-runtime-compose-samples"))
     docs(project(":lifecycle:lifecycle-runtime-ktx"))
@@ -276,9 +276,9 @@ dependencies {
     docs(project(":navigation:navigation-testing"))
     docs(project(":navigation:navigation-ui"))
     docs(project(":navigation:navigation-ui-ktx"))
-    docs(project(":paging:paging-common"))
+    kmpDocs(project(":paging:paging-common"))
     docs(project(":paging:paging-common-ktx"))
-    docs(project(":paging:paging-compose"))
+    kmpDocs(project(":paging:paging-compose"))
     samples(project(":paging:paging-compose:paging-compose-samples"))
     docs(project(":paging:paging-guava"))
     docs(project(":paging:paging-runtime"))
@@ -287,7 +287,7 @@ dependencies {
     docs(project(":paging:paging-rxjava2-ktx"))
     docs(project(":paging:paging-rxjava3"))
     samples(project(":paging:paging-samples"))
-    docs(project(":paging:paging-testing"))
+    kmpDocs(project(":paging:paging-testing"))
     docs(project(":palette:palette"))
     docs(project(":palette:palette-ktx"))
     docs(project(":pdf:pdf-viewer"))
@@ -313,7 +313,7 @@ dependencies {
     docs(project(":recyclerview:recyclerview-selection"))
     docs(project(":remotecallback:remotecallback"))
     docs(project(":resourceinspection:resourceinspection-annotation"))
-    docs(project(":room:room-common"))
+    kmpDocs(project(":room:room-common"))
     docs(project(":room:room-guava"))
     docs(project(":room:room-ktx"))
     docs(project(":room:room-migration"))
@@ -321,7 +321,7 @@ dependencies {
     docs(project(":room:room-paging-guava"))
     docs(project(":room:room-paging-rxjava2"))
     docs(project(":room:room-paging-rxjava3"))
-    docs(project(":room:room-runtime"))
+    kmpDocs(project(":room:room-runtime"))
     docs(project(":room:room-rxjava2"))
     docs(project(":room:room-rxjava3"))
     docs(project(":room:room-testing"))
@@ -341,9 +341,9 @@ dependencies {
     docs(project(":slice:slice-remotecallback"))
     docs(project(":slice:slice-view"))
     docs(project(":slidingpanelayout:slidingpanelayout"))
-    docs(project(":sqlite:sqlite"))
+    kmpDocs(project(":sqlite:sqlite"))
     kmpDocs(project(":sqlite:sqlite-bundled"))
-    docs(project(":sqlite:sqlite-framework"))
+    kmpDocs(project(":sqlite:sqlite-framework"))
     docs(project(":sqlite:sqlite-ktx"))
     docs(project(":startup:startup-runtime"))
     docs(project(":swiperefreshlayout:swiperefreshlayout"))
@@ -420,7 +420,7 @@ dependencies {
     stubs(project(":window:extensions:core:core"))
     stubs(project(":window:extensions:extensions"))
     stubs(project(":window:sidecar:sidecar"))
-    docs(project(":window:window-core"))
+    kmpDocs(project(":window:window-core"))
     docs(project(":window:window-java"))
     docs(project(":window:window-rxjava2"))
     docs(project(":window:window-rxjava3"))
diff --git a/paging/paging-common/src/commonJvmAndroidMain/kotlin/androidx/paging/ItemKeyedDataSource.jvm.kt b/paging/paging-common/src/commonJvmAndroidMain/kotlin/androidx/paging/ItemKeyedDataSource.jvm.kt
index 8aeb85ab60c..abc578591b5 100644
--- a/paging/paging-common/src/commonJvmAndroidMain/kotlin/androidx/paging/ItemKeyedDataSource.jvm.kt
+++ b/paging/paging-common/src/commonJvmAndroidMain/kotlin/androidx/paging/ItemKeyedDataSource.jvm.kt
@@ -55,15 +55,15 @@ public abstract class ItemKeyedDataSource<Key : Any, Value : Any> : DataSource<K
      * Holder object for inputs to [loadInitial].
      *
      * @param Key Type of data used to query [Value] types out of the [DataSource].
-     * @property requestedInitialKey Load items around this key, or at the beginning of the data set
+     * @param requestedInitialKey Load items around this key, or at the beginning of the data set
      * if `null` is passed.
      *
      * Note that this key is generally a hint, and may be ignored if you want to always load from
      * the beginning.
-     * @property requestedLoadSize Requested number of items to load.
+     * @param requestedLoadSize Requested number of items to load.
      *
      * Note that this may be larger than available data.
-     * @property placeholdersEnabled Defines whether placeholders are enabled, and whether the
+     * @param placeholdersEnabled Defines whether placeholders are enabled, and whether the
      * loaded total count will be ignored.
      */
     public open class LoadInitialParams<Key : Any>(
@@ -79,10 +79,10 @@ public abstract class ItemKeyedDataSource<Key : Any, Value : Any> : DataSource<K
      * Holder object for inputs to [loadBefore] and [loadAfter].
      *
      * @param Key Type of data used to query [Value] types out of the [DataSource].
-     * @property key Load items before/after this key.
+     * @param key Load items before/after this key.
      *
      * Returned data must begin directly adjacent to this position.
-     * @property requestedLoadSize Requested number of items to load.
+     * @param requestedLoadSize Requested number of items to load.
      *
      * Returned page can be of this size, but it may be altered if that is easier, e.g. a network
      * data source where the backend defines page size.
diff --git a/paging/paging-common/src/commonJvmAndroidMain/kotlin/androidx/paging/PageKeyedDataSource.jvm.kt b/paging/paging-common/src/commonJvmAndroidMain/kotlin/androidx/paging/PageKeyedDataSource.jvm.kt
index e0d393bc476..5f229650767 100644
--- a/paging/paging-common/src/commonJvmAndroidMain/kotlin/androidx/paging/PageKeyedDataSource.jvm.kt
+++ b/paging/paging-common/src/commonJvmAndroidMain/kotlin/androidx/paging/PageKeyedDataSource.jvm.kt
@@ -54,10 +54,10 @@ public abstract class PageKeyedDataSource<Key : Any, Value : Any> : DataSource<K
      * Holder object for inputs to [loadInitial].
      *
      * @param Key Type of data used to query pages.
-     * @property requestedLoadSize Requested number of items to load.
+     * @param requestedLoadSize Requested number of items to load.
      *
      * Note that this may be larger than available data.
-     * @property placeholdersEnabled Defines whether placeholders are enabled, and whether the
+     * @param placeholdersEnabled Defines whether placeholders are enabled, and whether the
      * loaded total count will be ignored.
      */
     public open class LoadInitialParams<Key : Any>(
@@ -69,10 +69,10 @@ public abstract class PageKeyedDataSource<Key : Any, Value : Any> : DataSource<K
      * Holder object for inputs to [loadBefore] and [loadAfter].
      *
      * @param Key Type of data used to query pages.
-     * @property key Load items before/after this key.
+     * @param key Load items before/after this key.
      *
      * Returned data must begin directly adjacent to this position.
-     * @property requestedLoadSize Requested number of items to load.
+     * @param requestedLoadSize Requested number of items to load.
      *
      * Returned page can be of this size, but it may be altered if that is easier, e.g. a network
      * data source where the backend defines page size.
diff --git a/paging/paging-common/src/commonMain/kotlin/androidx/paging/LoadState.kt b/paging/paging-common/src/commonMain/kotlin/androidx/paging/LoadState.kt
index d554721cb50..2841b9f80e3 100644
--- a/paging/paging-common/src/commonMain/kotlin/androidx/paging/LoadState.kt
+++ b/paging/paging-common/src/commonMain/kotlin/androidx/paging/LoadState.kt
@@ -89,7 +89,7 @@ public sealed class LoadState(
      *
      * @param error [Throwable] that caused the load operation to generate this error state.
      *
-     * @see androidx.paging.PagedList.retry
+     * @see androidx.paging.PagedList#retry
      */
     public class Error(
         public val error: Throwable
diff --git a/room/room-runtime/src/commonMain/kotlin/androidx/room/RoomDatabase.kt b/room/room-runtime/src/commonMain/kotlin/androidx/room/RoomDatabase.kt
index 13ba545b7ea..bb3ec2396ee 100644
--- a/room/room-runtime/src/commonMain/kotlin/androidx/room/RoomDatabase.kt
+++ b/room/room-runtime/src/commonMain/kotlin/androidx/room/RoomDatabase.kt
@@ -181,7 +181,7 @@ expect abstract class RoomDatabase {
     /**
      * Journal modes for SQLite database.
      *
-     * @see Builder.setJournalMode
+     * @see Builder#setJournalMode
      */
     enum class JournalMode {
         /**