diff --git a/build.gradle b/build.gradle
index 4b7173c4308..15d24943117 100644
--- a/build.gradle
+++ b/build.gradle
@@ -98,6 +98,10 @@ subprojects {
     }
     // ignore missing javadocs
     tasks.withType(Javadoc) { Javadoc javadoc ->
+      // the -quiet here is because of a bug in gradle, in that adding a string option
+      // by itself is not added to the options. By adding quiet, both this option and
+      // the "value" -quiet is added, separated by a space. This is ok since the javadoc
+      // command already adds -quiet, so we are just duplicating it
       javadoc.options.addStringOption('Xdoclint:all,-missing', '-quiet')
     }
   }