[build] Treat javadoc warnings as errors in CI and fix warnings (#3530)

docs/build.gradle

@@ -130,6 +130,19 @@ task generateJavaDocs(type: Javadoc) {
     title = "WPILib API ${wpilibVersioning.version.get()}"
     ext.entryPoint = "$destinationDir/index.html"
 
+    if (JavaVersion.current().isJava8Compatible() && project.hasProperty('buildServer')) {
+        // Treat javadoc warnings as errors.
+        //
+        // The second argument '-quiet' is a hack. The one paramater
+        // addStringOption() doesn't work, so we add '-quiet', which is added
+        // anyway by gradle. See https://github.com/gradle/gradle/issues/2354.
+        //
+        // See JDK-8200363 (https://bugs.openjdk.java.net/browse/JDK-8200363)
+        // for information about the nonstandard -Xwerror option. JDK 15+ has
+        // -Werror.
+        options.addStringOption('Xwerror', '-quiet')
+    }
+
     if (JavaVersion.current().isJava11Compatible()) {
         if (!JavaVersion.current().isJava12Compatible()) {
             options.addBooleanOption('-no-module-directories', true)

wpilibj/src/main/java/edu/wpi/first/wpilibj/PowerDistribution.java

@@ -36,7 +36,8 @@ public class PowerDistribution implements Sendable, AutoCloseable {
   /**
    * Constructs a PowerDistribution.
    *
-   * @param module The CAN ID of the PDP
+   * @param module The CAN ID of the PDP.
+   * @param moduleType Module type (automatic, CTRE, or REV).
    */
   public PowerDistribution(int module, ModuleType moduleType) {
     m_handle = PowerDistributionJNI.initialize(module, moduleType.value);

wpimath/src/main/java/edu/wpi/first/math/geometry/Transform2d.java

@@ -60,6 +60,7 @@ public class Transform2d {
    * Composes two transformations.
    *
    * @param other The transform to compose with this one.
+   * @return The composition of the two transformations.
    */
   public Transform2d plus(Transform2d other) {
     return new Transform2d(new Pose2d(), new Pose2d().transformBy(this).transformBy(other));

wpimath/src/main/native/include/frc/geometry/Transform2d.h

@@ -85,6 +85,7 @@ class Transform2d {
    * Composes two transformations.
    *
    * @param other The transform to compose with this one.
+   * @return The composition of the two transformations.
    */
   Transform2d operator+(const Transform2d& other) const;