Update comments about the option processor.

There were a few places where the current state of the world was not clear.

RELNOTES: None.
PiperOrigin-RevId: 167273651

2 files changed, 18 insertions, 6 deletions

diff --git a/src/main/java/com/google/devtools/common/options/Option.java b/src/main/java/com/google/devtools/common/options/Option.java
index 829f9e98b7..4a65f69abc 100644
--- a/src/main/java/com/google/devtools/common/options/Option.java
+++ b/src/main/java/com/google/devtools/common/options/Option.java
@@ -23,6 +23,9 @@ import java.lang.annotation.Target;
  *
  * <p>The fields of this annotation have matching getters in {@link OptionDefinition}. Please do not
  * access these fields directly, but instead go through that class.
+ *
+ * <p>A number of checks are run on an Option's fields' values at compile time. See
+ * {@link com.google.devtools.common.options.processor.OptionProcessor} for details.
  */
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
@@ -85,9 +88,6 @@ public @interface Option {
    *
    * <p>For undocumented flags that aren't listed anywhere, set this to
    * OptionDocumentationCategory.UNDOCUMENTED.
-   *
-   * <p>For hidden or internal options, please set this as UNDOCUMENTED and set the specific reason
-   * for this state in the metadataTags() field.
    */
   OptionDocumentationCategory documentationCategory();
 
@@ -107,6 +107,8 @@ public @interface Option {
    *
    * <p>If one or more of the OptionMetadataTag values apply, please include, but otherwise, this
    * list can be left blank.
+   *
+   * <p>Hidden or internal options must be UNDOCUMENTED (set in {@link #documentationCategory()}).
    */
   OptionMetadataTag[] metadataTags() default {};
 
diff --git a/src/main/java/com/google/devtools/common/options/processor/OptionProcessor.java b/src/main/java/com/google/devtools/common/options/processor/OptionProcessor.java
index d0a1eebb55..7474408a9d 100644
--- a/src/main/java/com/google/devtools/common/options/processor/OptionProcessor.java
+++ b/src/main/java/com/google/devtools/common/options/processor/OptionProcessor.java
@@ -56,9 +56,19 @@ import javax.tools.Diagnostic;
 /**
  * Annotation processor for {@link Option}.
  *
- * <p>The {@link OptionsParser} only accepts publicly declared options in {@link
- * OptionsBase}-inheriting classes, and there is no support for {@link Option} annotated fields
- * declared elsewhere or privately. Prevent such uses from compiling.
+ * <p>Checks the following invariants about {@link Option}-annotated fields ("options"):
+ * <ul>
+ * <li>The {@link OptionsParser} only accepts options in {@link OptionsBase}-inheriting classes
+ * <li>All options must be declared publicly and be neither static nor final.
+ * <li>All options that must be used on the command line must have sensible names without
+ *       whitespace or other confusing characters, such as equal signs.
+ * <li>The type of the option must match the converter that will convert the unparsed string value
+ *       into the option type. For options that do not specify a converter, check that there is a
+ *       valid match in the {@link Converters#DEFAULT_CONVERTERS} list.
+ * <li>Options must list valid combinations of tags and documentation categories.
+ * </ul>
+ *
+ * <p>These properties can be relied upon at runtime without additional checks.
  */
 @SupportedAnnotationTypes({"com.google.devtools.common.options.Option"})
 @SupportedSourceVersion(SourceVersion.RELEASE_8)