javadoc_combined.gradle

// Copyright (C) 2017 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
apply from: "${buildscript.sourceFile.parentFile}/constants.gradle"
apply from: "${buildscript.sourceFile.parentFile}/javadoc_util.gradle"

class CombinedJavadocPlugin implements Plugin<Project> {

  static final String JAVADOC_TASK_NAME = "generateCombinedJavadoc"
  static final String DACKKA_TASK_NAME = "generateCombinedDackka"

  // Dackka snapshots are listed at https://androidx.dev/dackka/builds.
  static final String DACKKA_JAR_URL =
      "https://androidx.dev/dackka/builds/9221390/artifacts/dackka-1.0.4-all.jar"

  @Override
  void apply(Project project) {
    project.gradle.projectsEvaluated {
      Set<Project> libraryModules = getLibraryModules(project)
      if (!libraryModules.isEmpty()) {
        def guavaReferenceUrl = "https://guava.dev/releases/$project.ext.guavaVersion/api/docs"

        project.task(JAVADOC_TASK_NAME, type: Javadoc) {
          description = "Generates combined Javadoc."
          title = "ExoPlayer library"
          source = libraryModules.generateJavadoc.source
          classpath = project.files([])
          destinationDir = project.file("$project.buildDir/docs/javadoc")
          options {
            links "https://developer.android.com/reference", guavaReferenceUrl
            encoding = "UTF-8"
          }
          options.addBooleanOption "-no-module-directories", true
          exclude "**/BuildConfig.java"
          exclude "**/R.java"
          doFirst {
            libraryModules.each { libraryModule ->
              libraryModule.android.libraryVariants.all { variant ->
                def name = variant.buildType.name
                if (name == "release") {
                  // Works around b/234569640 that causes different versions of the androidx.media
                  // jar to be on the classpath.
                  def allJarFiles = []
                  allJarFiles.addAll(variant.javaCompileProvider.get().classpath.files)
                  def filteredJarFiles = allJarFiles.findAll { file ->
                    if (file ==~ /.*media-.\..\..-api.jar$/
                        && !file.path.endsWith(
                            "media-" + project.ext.androidxMediaVersion + "-api.jar")) {
                      return false;
                    }
                    if (file ==~ /.*\/core-.\..\..-api.jar$/
                            && !file.path.endsWith(
                            "core-" + project.ext.androidxCoreVersion + "-api.jar")) {
                      return false;
                    }
                    return true;
                  }
                  classpath +=
                      libraryModule.project.files(
                          filteredJarFiles,
                          libraryModule.project.android.getBootClasspath())
                }
              }
            }
          }
          doLast {
            libraryModules.each { libraryModule ->
              project.copy {
                from "${libraryModule.projectDir}/src/main/javadoc"
                into "${project.buildDir}/docs/javadoc"
              }
            }
            project.fixJavadoc()
          }
        }

        def dackkaOutputDir = project.file("$project.buildDir/docs/dackka")
        project.task(DACKKA_TASK_NAME, type: JavaExec) {
          doFirst {
            // Recreate the output directory to remove any leftover files from a previous run.
            project.delete dackkaOutputDir
            project.mkdir dackkaOutputDir

            // Download the Dackka JAR.
            new URL(DACKKA_JAR_URL).withInputStream {
              i -> classpath.getSingleFile().withOutputStream { it << i }
            }

            // Build lists of source files and dependencies.
            def sources = []
            def dependencies = []
            libraryModules.each { libraryModule ->
              libraryModule.android.libraryVariants.all { variant ->
                def name = variant.buildType.name
                if (name == "release") {
                  def classpathFiles =
                      project.files(variant.javaCompileProvider.get().classpath.files)
                  variant.sourceSets.inject(sources) {
                    acc, val -> acc << val.javaDirectories
                  }
                  dependencies << classpathFiles.filter { f -> !(f.path.contains("/buildout/")) }
                  dependencies << libraryModule.project.android.getBootClasspath()
                }
              }
            }

            // Set command line arguments to Dackka.
            def guavaPackageListFile = getGuavaPackageListFile(getTemporaryDir())
            def globalLinksString = "$guavaReferenceUrl^$guavaPackageListFile^^"
            def sourcesString = project.files(sources.flatten())
                .filter({ f -> project.file(f).exists() }).join(";")
            def dependenciesString = project.files(dependencies).asPath.replace(':', ';')
            def sourceSet = [
                "-src", sourcesString,
                "-classpath", dependenciesString,
                "-documentedVisibilities", "PUBLIC;PROTECTED"
              ].join(" ")
            args("-moduleName", "",
                "-outputDir", "$dackkaOutputDir",
                "-globalLinks", "$globalLinksString",
                "-loggingLevel", "WARN",
                "-sourceSet", "$sourceSet",
                "-offlineMode")
            environment("DEVSITE_TENANT", "androidx/media3")
          }
          description = "Generates combined javadoc for developer.android.com."
          classpath = project.files(new File(getTemporaryDir(), "dackka.jar"))
          doLast {
            libraryModules.each { libraryModule ->
              project.copy {
                from "${libraryModule.projectDir}/src/main/javadoc"
                into "${dackkaOutputDir}/reference/"
              }
              project.copy {
                from "${libraryModule.projectDir}/src/main/javadoc"
                into "${dackkaOutputDir}/reference/kotlin/"
              }
            }
          }
        }
      }
    }
  }

  // Returns Android library modules that declare a generateJavadoc task.
  private static Set<Project> getLibraryModules(Project project) {
    project.subprojects.findAll {
      it.plugins.findPlugin("com.android.library") &&
      it.tasks.findByName("generateJavadoc")
    }
  }

  // Returns a file containing the list of packages that should be linked to Guava documentation.
  private static File getGuavaPackageListFile(File directory) {
    def packageListFile = new File(directory, "guava")
    packageListFile.text = ["com.google.common.base", "com.google.common.collect",
                            "com.google.common.io", "com.google.common.math",
                            "com.google.common.net", "com.google.common.primitives",
                            "com.google.common.truth", "com.google.common.util.concurrent"]
        .join('\n')
    return packageListFile
  }

}

apply plugin: CombinedJavadocPlugin