Merge branch 'master' of https://github.com/firebase/firebase-android-sdk into rpf-add-coroutines-common-ktx

Author: thatfiredev

buildSrc/src/main/java/com/google/firebase/gradle/bomgenerator/BomGeneratorTask.java

@@ -54,6 +54,7 @@ public class BomGeneratorTask extends DefaultTask {
           "com.google.firebase:firebase-analytics-ktx",
           "com.google.firebase:firebase-appcheck-debug",
           "com.google.firebase:firebase-appcheck-debug-testing",
+          "com.google.firebase:firebase-appcheck-ktx",
           "com.google.firebase:firebase-appcheck-playintegrity",
           "com.google.firebase:firebase-appcheck-safetynet",
           "com.google.firebase:firebase-appcheck",

buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaGenerationTask.kt

@@ -3,6 +3,7 @@ package com.google.firebase.gradle.plugins
 import java.io.File
 import javax.inject.Inject
 import org.gradle.api.DefaultTask
+import org.gradle.api.file.FileCollection
 import org.gradle.api.provider.ListProperty
 import org.gradle.api.provider.Property
 import org.gradle.api.provider.SetProperty
@@ -38,7 +39,7 @@ abstract class GenerateDocumentationTaskExtension : DefaultTask() {
     abstract val dackkaJarFile: Property<File>
 
     @get:[InputFiles Classpath]
-    abstract val dependencies: ListProperty<File>
+    abstract val dependencies: Property<FileCollection>
 
     @get:InputFiles
     @get:PathSensitive(PathSensitivity.RELATIVE)
@@ -127,7 +128,8 @@ abstract class GenerateDocumentationTask @Inject constructor(
             "android" to "https://developer.android.com/reference/kotlin/",
             "google" to "https://developers.google.com/android/reference/",
             "firebase" to "https://firebase.google.com/docs/reference/kotlin/",
-            "coroutines" to "https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/"
+            "coroutines" to "https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/",
+            "kotlin" to "https://kotlinlang.org/api/latest/jvm/stdlib/"
         )
 
         return packageLists.get().map {

buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt

@@ -90,26 +90,23 @@ tasks above). While we do not currently offer any configuration for the Dackka
 plugin, this could change in the future as needed. Currently, the DackkaPlugin
 provides sensible defaults to output directories, package lists, and so forth.
 
-The DackkaPlugin also provides two extra tasks:
-[cleanDackkaDocumentation][registerCleanDackkaDocumentation] and
-[deleteDackkaGeneratedJavaReferences][registerDeleteDackkaGeneratedJavaReferencesTask].
+The DackkaPlugin also provides three extra tasks:
+[cleanDackkaDocumentation][registerCleanDackkaDocumentation],
+[copyJavaDocToCommonDirectory][registerCopyJavaDocToCommonDirectoryTask] and
+[copyKotlinDocToCommonDirectory][registerCopyKotlinDocToCommonDirectoryTask].
 
 _cleanDackkaDocumentation_ is exactly what it sounds like, a task to clean up (delete)
 the output of Dackka. This is useful when testing Dackka outputs itself- and
 shouldn't be apart of the normal flow. The reasoning is that it would otherwise
 invalidate the gradle cache.
 
-_deleteDackkaGeneratedJavaReferences_ is a temporary addition. Dackka generates
-two separate styles of docs for every source set: Java & Kotlin. Regardless of
-whether the source is in Java or Kotlin. The Java output is how the source looks
-from Java, and the Kotlin output is how the source looks from Kotlin. We publish
-these under two separate categories, which you can see here:
-[Java](https://firebase.google.com/docs/reference/android/packages)
-or
-[Kotlin](https://firebase.google.com/docs/reference/kotlin/packages).
-Although, we do not currently publish Java packages with Dackka- and will wait
-until we are more comfortable with the output of Dackka to do so. So until then,
-this task will remove all generate Java references from the Dackka output.
+_copyJavaDocToCommonDirectory_ copies the JavaDoc variant of the Dackka output for each sdk,
+and pastes it in a common directory under the root project's build directory. This makes it easier
+to zip the doc files for staging.
+
+_copyKotlinDocToCommonDirectory_ copies the KotlinDoc variant of the Dackka output for each sdk,
+and pastes it in a common directory under the root project's build directory. This makes it easier
+to zip the doc files for staging.
 
 Currently, the DackkaPlugin builds Java sources separate from Kotlin Sources. There is an open bug
 for Dackka in which hidden parent classes and annotations do not hide themselves from children classes.
@@ -123,18 +120,19 @@ abstract class DackkaPlugin : Plugin<Project> {
         project.afterEvaluate {
             if (shouldWePublish(project)) {
                 val generateDocumentation = registerGenerateDackkaDocumentationTask(project)
-                val outputDirectory = generateDocumentation.flatMap { it.outputDirectory }
-                val firesiteTransform = registerFiresiteTransformTask(project, outputDirectory)
-                val deleteJavaReferences = registerDeleteDackkaGeneratedJavaReferencesTask(project, outputDirectory)
-                val copyOutputToCommonDirectory = registerCopyDackkaOutputToCommonDirectoryTask(project, outputDirectory)
+                val dackkaFilesDirectory = generateDocumentation.flatMap { it.outputDirectory }
+                val firesiteTransform = registerFiresiteTransformTask(project, dackkaFilesDirectory)
+                val transformedFilesDirectory = firesiteTransform.flatMap { it.outputDirectory }
+                val copyJavaDocToCommonDirectory = registerCopyJavaDocToCommonDirectoryTask(project, transformedFilesDirectory)
+                val copyKotlinDocToCommonDirectory = registerCopyKotlinDocToCommonDirectoryTask(project, transformedFilesDirectory)
 
                 project.tasks.register("kotlindoc") {
                     group = "documentation"
                     dependsOn(
                         generateDocumentation,
                         firesiteTransform,
-                        deleteJavaReferences,
-                        copyOutputToCommonDirectory
+                        copyJavaDocToCommonDirectory,
+                        copyKotlinDocToCommonDirectory
                     )
                 }
             } else {
@@ -171,6 +169,7 @@ abstract class DackkaPlugin : Plugin<Project> {
                     val classpath = compileConfiguration.getJars() + project.javadocConfig.getJars() + project.files(bootClasspath)
 
                     val sourcesForJava = sourceSets.flatMap {
+                        // TODO(b/246984444): Investigate why kotlinDirectories includes javaDirectories
                         it.javaDirectories.map { it.absoluteFile }
                     }
 
@@ -180,13 +179,12 @@ abstract class DackkaPlugin : Plugin<Project> {
                     }
 
                     docsTask.configure {
-                        clientName.set(project.firebaseConfigValue { artifactId })
-                        // this will become useful with the agp upgrade, as they're separate in 7.x+
-                        val sourcesForKotlin = emptyList<File>()
+                        if (!isKotlin) dependsOn(docStubs)
+
+                        val sourcesForKotlin = emptyList<File>() + projectSpecificSources(project)
                         val packageLists = fetchPackageLists(project)
 
-                        if (!isKotlin) dependsOn(docStubs)
-                        val excludedFiles = if (!isKotlin) projectSpecificSuppressedFiles(project) else emptyList()
+                        val excludedFiles = projectSpecificSuppressedFiles(project)
                         val fixedJavaSources = if (!isKotlin) listOf(project.docStubs) else sourcesForJava
 
                         javaSources.set(fixedJavaSources)
@@ -209,11 +207,20 @@ abstract class DackkaPlugin : Plugin<Project> {
             include("**/package-list")
         }.toList()
 
+    // TODO(b/243534168): Remove when fixed
+    private fun projectSpecificSources(project: Project) =
+        when (project.name) {
+            "firebase-common" -> {
+                project.project(":firebase-firestore").files("src/main/java/com/google/firebase").toList()
+            }
+            else -> emptyList()
+        }
+
     // TODO(b/243534168): Remove when fixed
     private fun projectSpecificSuppressedFiles(project: Project): List<File> =
         when (project.name) {
             "firebase-common" -> {
-                project.files("${project.docStubs}/com/google/firebase/firestore").toList()
+                project.project(":firebase-firestore").files("src/main/java/com/google/firebase/firestore").toList()
             }
             "firebase-firestore" -> {
                 project.files("${project.docStubs}/com/google/firebase/Timestamp.java").toList()
@@ -229,43 +236,50 @@ abstract class DackkaPlugin : Plugin<Project> {
 
         dackkaJarFile.set(dackkaFile)
         outputDirectory.set(dackkaOutputDirectory)
+        clientName.set(project.firebaseConfigValue { artifactId })
     }
 
-    // TODO(b/243833009): Make task cacheable
-    private fun registerFiresiteTransformTask(project: Project, outputDirectory: Provider<File>) =
+    private fun registerFiresiteTransformTask(project: Project, dackkaFilesDirectory: Provider<File>) =
         project.tasks.register<FiresiteTransformTask>("firesiteTransform") {
-            dackkaFiles.set(outputDirectory)
-        }
-
-    // If we decide to publish java variants, we'll need to address the generated format as well
-    // TODO(b/243833009): Make task cacheable
-    private fun registerDeleteDackkaGeneratedJavaReferencesTask(project: Project, outputDirectory: Provider<File>) =
-        project.tasks.register<Delete>("deleteDackkaGeneratedJavaReferences") {
             mustRunAfter("generateDackkaDocumentation")
 
-            val filesWeDoNotNeed = listOf(
-                "reference/client",
-                "reference/com"
-            )
-            val filesToDelete = outputDirectory.map { dir ->
-                filesWeDoNotNeed.map {
-                    project.files("${dir.path}/$it")
-                }
-            }
+            dackkaFiles.set(dackkaFilesDirectory)
+            outputDirectory.set(project.file("${project.buildDir}/dackkaTransformedFiles"))
+        }
 
-            delete(filesToDelete)
+    // TODO(b/246593212): Migrate doc files to single directory
+    private fun registerCopyJavaDocToCommonDirectoryTask(project: Project, outputDirectory: Provider<File>) =
+        project.tasks.register<Copy>("copyJavaDocToCommonDirectory") {
+            /**
+             * This is not currently cache compliant. The need for this property is
+             * temporary while we test it alongside the current javaDoc task. Since it's such a
+             * temporary behavior, losing cache compliance is fine for now.
+             */
+            if (project.rootProject.findProperty("dackkaJavadoc") == "true") {
+                mustRunAfter("firesiteTransform")
+
+                val outputFolder = project.file("${project.rootProject.buildDir}/firebase-kotlindoc/android")
+                val clientFolder = outputDirectory.map { project.file("${it.path}/reference/client") }
+                val comFolder = outputDirectory.map { project.file("${it.path}/reference/com") }
+
+                fromDirectory(clientFolder)
+                fromDirectory(comFolder)
+
+                into(outputFolder)
+            }
         }
 
-    private fun registerCopyDackkaOutputToCommonDirectoryTask(project: Project, outputDirectory: Provider<File>) =
-        project.tasks.register<Copy>("copyDackkaOutputToCommonDirectory") {
-            mustRunAfter("deleteDackkaGeneratedJavaReferences")
+    // TODO(b/246593212): Migrate doc files to single directory
+    private fun registerCopyKotlinDocToCommonDirectoryTask(project: Project, outputDirectory: Provider<File>) =
+        project.tasks.register<Copy>("copyKotlinDocToCommonDirectory") {
             mustRunAfter("firesiteTransform")
 
-            val referenceFolder = outputDirectory.map { project.file("${it.path}/reference") }
             val outputFolder = project.file("${project.rootProject.buildDir}/firebase-kotlindoc")
+            val kotlinFolder = outputDirectory.map { project.file("${it.path}/reference/kotlin") }
+
+            fromDirectory(kotlinFolder)
 
-            from(referenceFolder)
-            destinationDir = outputFolder
+            into(outputFolder)
         }
 
     // Useful for local testing, but may not be desired for standard use (that's why it's not depended on)
@@ -274,5 +288,7 @@ abstract class DackkaPlugin : Plugin<Project> {
             group = "cleanup"
 
             delete("${project.buildDir}/dackkaDocumentation")
+            delete("${project.buildDir}/dackkaTransformedFiles")
+            delete("${project.rootProject.buildDir}/firebase-kotlindoc")
         }
 }

buildSrc/src/main/java/com/google/firebase/gradle/plugins/FiresiteTransformTask.kt

@@ -3,7 +3,11 @@ package com.google.firebase.gradle.plugins
 import java.io.File
 import org.gradle.api.DefaultTask
 import org.gradle.api.provider.Property
+import org.gradle.api.tasks.CacheableTask
 import org.gradle.api.tasks.InputDirectory
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
 import org.gradle.api.tasks.TaskAction
 
 /**
@@ -21,10 +25,15 @@ import org.gradle.api.tasks.TaskAction
  *  **Please note:**
  *  This task is idempotent- meaning it can safely be ran multiple times on the same set of files.
  */
+@CacheableTask
 abstract class FiresiteTransformTask : DefaultTask() {
     @get:InputDirectory
+    @get:PathSensitive(PathSensitivity.RELATIVE)
     abstract val dackkaFiles: Property<File>
 
+    @get:OutputDirectory
+    abstract val outputDirectory: Property<File>
+
     @TaskAction
     fun build() {
         val namesOfFilesWeDoNotNeed = listOf(
@@ -33,14 +42,18 @@ abstract class FiresiteTransformTask : DefaultTask() {
             "packages.html",
             "package-list"
         )
+        val rootDirectory = dackkaFiles.get()
+        val targetDirectory = outputDirectory.get()
+        targetDirectory.deleteRecursively()
+
+        rootDirectory.walkTopDown().forEach {
+            if (it.name !in namesOfFilesWeDoNotNeed) {
+                val relativePath = it.toRelativeString(rootDirectory)
+                val newFile = it.copyTo(File("${targetDirectory.path}/$relativePath"), true)
 
-        dackkaFiles.get().walkTopDown().forEach {
-            if (it.name in namesOfFilesWeDoNotNeed) {
-                it.delete()
-            } else {
                 when (it.extension) {
-                    "html" -> it.fixHTMLFile()
-                    "yaml" -> it.fixYamlFile()
+                    "html" -> newFile.fixHTMLFile()
+                    "yaml" -> newFile.fixYamlFile()
                 }
             }
         }

buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt

@@ -0,0 +1,10 @@
+package com.google.firebase.gradle.plugins
+
+import java.io.File
+import org.gradle.api.provider.Provider
+import org.gradle.api.tasks.Copy
+
+fun Copy.fromDirectory(directory: Provider<File>) =
+    from(directory) {
+        into(directory.map { it.name })
+    }

buildSrc/src/main/java/com/google/firebase/gradle/plugins/Metalava.kt

@@ -23,6 +23,7 @@ import org.gradle.api.artifacts.Configuration
 import org.gradle.api.file.FileCollection
 import org.gradle.api.provider.Property
 import org.gradle.api.provider.SetProperty
+import org.gradle.api.tasks.Classpath
 import org.gradle.api.tasks.Input
 import org.gradle.api.tasks.InputFile
 import org.gradle.api.tasks.InputFiles
@@ -68,7 +69,7 @@ abstract class GenerateStubsTask : DefaultTask() {
     @get:InputFiles
     abstract val sources: SetProperty<File>
 
-    @get:InputFiles
+    @get:[InputFiles Classpath]
     lateinit var classPath: FileCollection
 
     @get:OutputDirectory

buildSrc/src/main/java/com/google/firebase/gradle/plugins/ProjectUtils.kt

@@ -17,6 +17,7 @@ import org.gradle.api.Project
 import org.gradle.api.Task
 import org.gradle.api.artifacts.Configuration
 import org.gradle.api.attributes.Attribute
+import org.gradle.api.provider.Provider
 
 fun Project.isAndroid(): Boolean =
         listOf("com.android.application", "com.android.library", "com.android.test")
@@ -50,8 +51,7 @@ val Project.dackkaConfig: Configuration
  */
 fun Configuration.getJars() = incoming.artifactView {
     attributes {
-        // TODO(b/241795594): replace value with android-class instead of jar after agp upgrade
-        attribute(Attribute.of("artifactType", String::class.java), "jar")
+        attribute(Attribute.of("artifactType", String::class.java), "android-classes")
     }
 }.artifacts.artifactFiles
 
@@ -63,6 +63,14 @@ fun <T : Task, R : Task> T.dependsOnAndMustRunAfter(otherTask: R) {
     dependsOn(otherTask)
 }
 
+/**
+ * Utility method to call [Task.mustRunAfter] and [Task.dependsOn] on the specified task
+ */
+fun <T : Task, R : Task> T.dependsOnAndMustRunAfter(otherTask: Provider<R>) {
+    mustRunAfter(otherTask)
+    dependsOn(otherTask)
+}
+
 /**
  * Utility method to call [Task.mustRunAfter] and [Task.dependsOn] on the specified task name
  */