From edc626248f8aa892e8520b96dc098a4ffb77eb10 Mon Sep 17 00:00:00 2001 From: Daymon Date: Tue, 13 Sep 2022 14:43:08 -0500 Subject: [PATCH 1/4] Add util method for copying directories --- .../com/google/firebase/gradle/plugins/GradleUtils.kt | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt diff --git a/buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt b/buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt new file mode 100644 index 00000000000..76645416639 --- /dev/null +++ b/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) = + from(directory) { + into(directory.map { it.nameWithoutExtension }) + } From a56dd7d0ce01c472f6be44263da00e053f2a3b9f Mon Sep 17 00:00:00 2001 From: Daymon Date: Tue, 13 Sep 2022 14:43:24 -0500 Subject: [PATCH 2/4] Add javadoc support to our dackka plugin --- .../firebase/gradle/plugins/DackkaPlugin.kt | 76 +++++++++---------- 1 file changed, 37 insertions(+), 39 deletions(-) diff --git a/buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt b/buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt index aaff78844d0..da4345a342e 100644 --- a/buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt +++ b/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. @@ -125,16 +122,16 @@ abstract class DackkaPlugin : Plugin { 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 copyJavaDocToCommonDirectory = registerCopyJavaDocToCommonDirectoryTask(project, outputDirectory) + val copyKotlinDocToCommonDirectory = registerCopyKotlinDocToCommonDirectoryTask(project, outputDirectory) project.tasks.register("kotlindoc") { group = "documentation" dependsOn( generateDocumentation, firesiteTransform, - deleteJavaReferences, - copyOutputToCommonDirectory + copyJavaDocToCommonDirectory, + copyKotlinDocToCommonDirectory ) } } else { @@ -234,38 +231,39 @@ abstract class DackkaPlugin : Plugin { // TODO(b/243833009): Make task cacheable private fun registerFiresiteTransformTask(project: Project, outputDirectory: Provider) = project.tasks.register("firesiteTransform") { + mustRunAfter("generateDackkaDocumentation") + 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) = - project.tasks.register("deleteDackkaGeneratedJavaReferences") { - mustRunAfter("generateDackkaDocumentation") + // TODO(b/246593212): Migrate doc files to single directory + private fun registerCopyJavaDocToCommonDirectoryTask(project: Project, outputDirectory: Provider) = + project.tasks.register("copyJavaDocToCommonDirectory") { + if (project.rootProject.findProperty("dackkaJavadoc") == "true") { + mustRunAfter("firesiteTransform") - val filesWeDoNotNeed = listOf( - "reference/client", - "reference/com" - ) - val filesToDelete = outputDirectory.map { dir -> - filesWeDoNotNeed.map { - project.files("${dir.path}/$it") - } - } + 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) - delete(filesToDelete) + into(outputFolder) + } } - private fun registerCopyDackkaOutputToCommonDirectoryTask(project: Project, outputDirectory: Provider) = - project.tasks.register("copyDackkaOutputToCommonDirectory") { - mustRunAfter("deleteDackkaGeneratedJavaReferences") + // TODO(b/246593212): Migrate doc files to single directory + private fun registerCopyKotlinDocToCommonDirectoryTask(project: Project, outputDirectory: Provider) = + project.tasks.register("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) From a2ce22a6526659518382e5675bdd152d974925d3 Mon Sep 17 00:00:00 2001 From: Daymon Date: Tue, 13 Sep 2022 15:38:54 -0500 Subject: [PATCH 3/4] Remove the extension check on fromDirectory --- .../main/java/com/google/firebase/gradle/plugins/GradleUtils.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt b/buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt index 76645416639..d3a5b18a98f 100644 --- a/buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt +++ b/buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt @@ -6,5 +6,5 @@ import org.gradle.api.tasks.Copy fun Copy.fromDirectory(directory: Provider) = from(directory) { - into(directory.map { it.nameWithoutExtension }) + into(directory.map { it.name }) } From d571de819376f2a0cfe72bbbd768bc9c2bae5204 Mon Sep 17 00:00:00 2001 From: Daymon Date: Tue, 13 Sep 2022 15:39:17 -0500 Subject: [PATCH 4/4] Add a note about cache compliance and the javadoc task --- .../java/com/google/firebase/gradle/plugins/DackkaPlugin.kt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt b/buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt index da4345a342e..b274ca52b76 100644 --- a/buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt +++ b/buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt @@ -239,6 +239,11 @@ abstract class DackkaPlugin : Plugin { // TODO(b/246593212): Migrate doc files to single directory private fun registerCopyJavaDocToCommonDirectoryTask(project: Project, outputDirectory: Provider) = project.tasks.register("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")