[Build] Updated build to use Dackka for documentation generation

PiperOrigin-RevId: 730522331

Author: hunterstich

lib/build.gradle

@@ -1,4 +1,4 @@
-import org.gradle.internal.os.OperatingSystem
+import javax.inject.Inject
 
 apply plugin: 'com.android.library'
 apply plugin: 'maven-publish'
@@ -128,73 +128,6 @@ android {
   }
 }
 
-task generateJavadocs(type: Javadoc) {
-  if (project.hasProperty("online")) {
-    options.addStringOption("toroot", "/")
-    options.addStringOption("hdf", "android.whichdoc online")
-    options.addStringOption("hdf", "dac")
-    options.addBooleanOption("devsite", true)
-    options.addBooleanOption("yamlV2", true)
-    options.addStringOption("dac_libraryroot", "com/google/android/material")
-    options.addStringOption("dac_dataname", "MATERIAL_DATA")
-  }
-
-  if (project.hasProperty("docletPathRoot")) {
-    def docletPathRoot = project.property("docletPathRoot")
-    def outputPath = project.hasProperty("outputPath") ? project.property("outputPath") : "doclava-out"
-    def doclavaJar = project.getProperty("doclavaJar")
-
-    source = android.sourceSets.main.java.source
-    source = source.findAll { it.name.endsWith(".java") }
-
-    title = null
-    destinationDir = new File(outputPath)
-    classpath = files("${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar")
-    options.addStringOption("federate Android", "https://developer.android.com")
-    options.encoding = "UTF-8"
-    options.doclet = "com.google.doclava.Doclava"
-    options.docletpath = [
-      file(doclavaJar),
-      file(docletPathRoot + "/jsilver/v1_0_0/jsilver.jar")
-    ]
-  }
-}
-
-task getVersion {
-  doLast {
-    println version
-  }
-}
-
-def R_CLASS_PATH = "build/generated/not_namespaced_r_class_sources/releaseUnitTest/processReleaseUnitTestResources/r/com/google/android/material/R.java"
-Attribute<String> ARTIFACT_TYPE = Attribute.of("artifactType", String.class)
-afterEvaluate {
-  [generateJavadocs].forEach { task ->
-    task.dependsOn(':lib:processReleaseUnitTestResources')
-    task.source += R_CLASS_PATH
-
-    def releaseVariant = android.libraryVariants.find { it.name == 'release' }
-    if (releaseVariant == null) {
-      return
-    }
-
-    // Add transitive runtime dependencies to classpath
-    task.classpath += releaseVariant.runtimeConfiguration.incoming.artifactView { aView ->
-      aView.attributes.attribute(ARTIFACT_TYPE, "android-classes")
-    }.files
-
-    // Add project and compile dependencies to classpath
-    releaseVariant.javaCompileProvider.configure { javaCompileProvider ->
-      task.classpath += releaseVariant.getCompileClasspath(null)
-      task.classpath += task.project.files(javaCompileProvider.destinationDir)
-      task.source += javaCompileProvider.source
-    }
-
-    // Doclava does not understand -notimestamp option that is default since Gradle 6.0
-    task.options.setNoTimestamp(false)
-  }
-}
-
 task androidSourcesJar(type: Jar) {
   archiveClassifier.set('sources')
   from(android.sourceSets.main.java.srcDirs) {
@@ -250,3 +183,151 @@ afterEvaluate {
     }
   }
 }
+
+/**
+ * Generate library documentation.
+ *
+ * This task requires a Dackka jar to be run. This can be passed to the task
+ * by running the task from the command line and setting the --dackkaJar
+ * option.
+ *
+ * Example: ./gradlew generateDocumentation --dackkaJar="<path/to/dackka.jar>"
+ *
+ * The resulting documentation will be placed in `lib/build/docs` and contain
+ * documentation for both java and kotlin clients.
+ *
+ * TODO: b/149338266 - Dackka does not support links to resources in documentation.
+ * TODO: b/396171398 - inheritDoc results hav formatting issues with Dackka.
+ */
+tasks.register("generateDocumentation", DackkaRunner) {
+  group = "Publishing"
+  description = "Generate javadocs using dackka"
+  version = mdcLibraryVersion
+  config = layout.buildDirectory.file("resources/dackka_config.json").get().asFile
+  outputDirectory = layout.buildDirectory.dir("docs").get()
+  // Add all the files from the main source set to be documented by dackka
+  sourceDirectories.setFrom(
+    android.sourceSets.main.java.srcDirs.absolutePath
+  )
+  dependenciesClasspath.setFrom(
+    files("${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar"),
+  )
+}
+
+/**
+ * A task that uses Dackka to generate javadoc.
+ */
+abstract class DackkaRunner extends DefaultTask {
+
+  private String dackkaJar;
+
+  /**
+   * Set the path to the Dackka jar to use by setting the --dackkaJar command
+   * line argument when running the gradle task used by this task.
+   *
+   * @param path the path to the dackka jar
+   */
+  @Option(option = "dackkaJar", description = "path to daccka jar")
+  void setDackkaJar(String path) {
+    this.dackkaJar = path
+  }
+
+  @Input
+  String getDackkaJar() {
+    return dackkaJar;
+  }
+
+  /**
+   * The Material library version of these docs.
+   *
+   * This should most likely match mdcLibraryVersion from the projects build
+   * file.
+   */
+  @Input
+  String version;
+
+  /** Source directories to be documented. */
+  @InputFiles
+  final ConfigurableFileCollection sourceDirectories = project.files()
+
+  @InputFiles
+  final ConfigurableFileCollection dependenciesClasspath = project.files();
+
+  /** A file that should be populated with the Dackka configuration. */
+  @OutputFile
+  abstract File config;
+
+  /** The output containing documentation generated by Dackka. */
+  @OutputDirectory
+  abstract Directory outputDirectory;
+
+  @Inject
+  abstract ExecOperations getExecOperations()
+
+  @TaskAction
+  void run() {
+    // Delete any previously generated documentation
+    outputDirectory.asFile.deleteDir()
+    // Populate the Dackka config json file with Material-specific properties
+    writeDackkaConfig()
+    // Run the Dackka jar and generate docs
+    getExecOperations().javaexec {
+      classpath(dackkaJar)
+      args(config.absolutePath)
+    }
+  }
+
+  /** Populate the Dackka config file with project specific values. */
+  private void writeDackkaConfig() {
+    def configContents = """
+    {
+      "modeuleName": "Material Components",
+      "moduleVersion": "$version",
+      "outputDir": "${outputDirectory.asFile.absolutePath}",
+      "offlineMode": "true",
+      "noJdkLink": "true",
+      "sourceSets": [
+        {
+          "moduleDisplayName": "lib",
+          "analysisPlatform": "jvm",
+          "externalDocumentationLinks": [],
+          "sourceSetID": {
+            "scopeId": "com",
+            "sourceSetName": "main"
+          },
+          "sourceRoots": [${sourceDirectories.collect { '"' + it.absolutePath + '"' }.join(", ")}],
+          "samples": [],
+          "includes": [],
+          "classpath": [${dependenciesClasspath.collect { '"' + it.absolutePath + '"'}.join(", ")}],
+          "sourceLinks": [],
+          "documentedVisibilities": ["PUBLIC", "PROTECTED"]
+        }
+      ],
+      "pluginsConfiguration": [
+        {
+          "fqPluginName": "com.google.devsite.DevsitePlugin",
+          "serializationFormat": "JSON",
+          "values": "${getDevsitePluginConfigValues()}"
+        }
+      ]
+    }
+    """.trim();
+
+    config.write(configContents)
+  }
+
+  /** Returns the Dackka Devsite plugin configuration json string. */
+  private String getDevsitePluginConfigValues() {
+    return """
+    {
+      "docRootPath": "reference",
+      "projectPath": "com/google/android/material",
+      "excludedPackages": [ ".*excluded.*" ],
+      "javaDocsPath": "",
+      "kotlinDocsPath": "kotlin",
+      "baseSourceLink": "https://github.com/material-components/material-components-android/blob/${version}/lib/java/%s",
+      "annotationsNotToDisplay": [ "java.lang.Override", "kotlin.ParameterName" ]
+    }
+    """.trim().replace("\n", "").replace('"', '\\\"')
+  }
+}

lib/java/com/google/android/material/carousel/MaskableFrameLayout.java

@@ -182,6 +182,12 @@ public RectF getMaskRectF() {
     return maskRect;
   }
 
+  /**
+   * Sets an {@link OnMaskChangedListener}.
+   *
+   * @param onMaskChangedListener a listener to receive callbacks for changes in the mask or null
+   *    to clear the listener.
+   */
   @Override
   public void setOnMaskChangedListener(@Nullable OnMaskChangedListener onMaskChangedListener) {
     this.onMaskChangedListener = onMaskChangedListener;

lib/java/com/google/android/material/snackbar/BaseTransientBottomBar.java

@@ -1376,6 +1376,12 @@ private void setBaseTransientBottomBar(
       delegate.setBaseTransientBottomBar(baseTransientBottomBar);
     }
 
+    /**
+     * Called when the user's input indicates that they want to swipe the given view.
+     *
+     * @param child View the user is attempting to swipe
+     * @return true if the view can be dismissed via swiping, false otherwise
+     */
     @Override
     public boolean canSwipeDismissView(View child) {
       return delegate.canSwipeDismissView(child);

lib/java/com/google/android/material/snackbar/Snackbar.java

@@ -97,6 +97,12 @@ public static class Callback extends BaseCallback<Snackbar> {
     /** Indicates that the Snackbar was dismissed from a new Snackbar being shown. */
     public static final int DISMISS_EVENT_CONSECUTIVE = BaseCallback.DISMISS_EVENT_CONSECUTIVE;
 
+    /**
+     * Called when the given {@link Snackbar} is visible.
+     *
+     * @param sb The snackbar which is now visible.
+     * @see Snackbar#show()
+     */
     @Override
     public void onShown(Snackbar sb) {
       // Stub implementation to make API check happy.

lib/java/com/google/android/material/tabs/TabLayout.java

@@ -2193,7 +2193,7 @@ public Tab setTag(@Nullable Object tag) {
      *
      * <p>Do not rely on this if using {@link TabLayout#setupWithViewPager(ViewPager)}
      *
-     * @param id, unique id for this tab
+     * @param id unique id for this tab
      */
     @NonNull
     @CanIgnoreReturnValue