better javadoc on annotations

rapier-aws-ssm/src/main/java/rapier/aws/ssm/AwsSsmStringParameter.java

@@ -25,12 +25,24 @@
 import java.lang.annotation.Target;
 
 /**
- * An annotation that indicates an injection site should be populated with the value of the given
- * <a href=
+ * Indicates an injection site should be populated with the value of the given <a href=
  * "https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html">AWS
- * SSM Parameter Store</a> string parameter. The value of the parameter is read at runtime and
- * injected into the annotated element. If the parameter is not set, the default value is used
- * instead, if given. If no default value is given, then the value is {@code null}.
+ * SSM Parameter Store</a> string parameter. The value of the parameter is read at runtime. If the
+ * parameter does not exist, then the default value is used instead, if given. If no default value
+ * is given, then the value is {@code null}.
+ * 
+ * <p>
+ * The annotated element must be one of the following types:
+ * 
+ * <ul>
+ * <li>{@link String}</li>
+ * <li>Any primitive type</li>
+ * <li>Any boxed primitive type</li>
+ * <li>Any class or interface {@code T} with a method {@code public static T valueOf(String)}</li>
+ * <li>Any class or interface {@code T} with a method
+ * {@code public static T fromString(String)}</li>
+ * <li>Any class or interface {@code T} with a constructor {@code public T(String)}</li>
+ * </ul>
  */
 @javax.inject.Qualifier
 @jakarta.inject.Qualifier
@@ -39,7 +51,14 @@
 public @interface AwsSsmStringParameter {
   public static final String DEFAULT_VALUE_NOT_SET = "__UNDEFINED__";
 
+  /**
+   * The name of the AWS SSM Parameter Store string parameter to fetch.
+   */
   public String value();
 
+  /**
+   * The optional default value to use if the AWS SSM Parameter Store string parameter does not
+   * exist.
+   */
   public String defaultValue() default "__UNDEFINED__";
 }

rapier-cli/src/main/java/rapier/cli/CliFlagParameter.java

@@ -24,18 +24,61 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Indicates an injection site should be populated with the value of the given flag parameter in the
+ * program arguments. If a default value is given, then the flag parameter is optional, and the
+ * given default value is used if it is not provided. If the default value is not set, and the
+ * injection site is {@code Nullable}, then the flag parameter is optional, and {@code null} is used
+ * if it is not provided. Otherwise, the flag parameter is required.
+ * 
+ * <p>
+ * The annotated element must be one of the following types:
+ * 
+ * <ul>
+ * <li>{@code boolean}</li>
+ * <li>{@code Boolean}</li>
+ * <li>Any class or interface {@code T} with a method {@code public static T valueOf(Boolean)}</li>
+ * <li>Any class or interface {@code T} with a constructor {@code public T(Boolean)}</li>
+ * </ul>
+ * 
+ * <p>
+ * Any or all of {@link #positiveShortName()}, {@link #positiveLongName()},
+ * {@link #negativeShortName()}, and {@link #negativeLongName()} may be set, but at least one must
+ * be set.
+ */
 @javax.inject.Qualifier
 @jakarta.inject.Qualifier
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
 public @interface CliFlagParameter {
+  /**
+   * The short name (e.g., {@code -x}, {@code -y}) of the parameter that represents the value
+   * {@code true}.
+   */
   public char positiveShortName() default '\0';
 
+  /**
+   * The long name (e.g., {@code --foo}, {@code --bar}) of the parameter that represents the value
+   * {@code true}.
+   */
   public String positiveLongName() default "";
 
+  /**
+   * The short name (e.g., {@code -x}, {@code -y}) of the parameter that represents the value
+   * {@code false}.
+   */
   public char negativeShortName() default '\0';
 
+  /**
+   * The long name (e.g., {@code --foo}, {@code --bar}) of the parameter that represents the value
+   * {@code false}.
+   */
   public String negativeLongName() default "";
 
+  /**
+   * The optional default value to use if the flag parameter is not provided.
+   * 
+   * @see CliFlagParameterValue
+   */
   public CliFlagParameterValue defaultValue() default CliFlagParameterValue.NONE;
 }

rapier-cli/src/main/java/rapier/cli/CliFlagParameterValue.java

@@ -20,18 +20,29 @@
 package rapier.cli;
 
 public enum CliFlagParameterValue {
+  /**
+   * No value, equivalent to {@code null}
+   */
   NONE {
     @Override
     public Boolean toBoolean() {
       return null;
     }
   },
+
+  /**
+   * The value {@code true}, equivalent to {@code Boolean.TRUE}
+   */
   TRUE {
     @Override
     public Boolean toBoolean() {
       return Boolean.TRUE;
     }
   },
+
+  /**
+   * The value {@code false}, equivalent to {@code Boolean.FALSE}
+   */
   FALSE {
     @Override
     public Boolean toBoolean() {

rapier-cli/src/main/java/rapier/cli/CliOptionParameter.java

@@ -24,16 +24,54 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Indicates an injection site should be populated with the value of the given option parameter in
+ * the program arguments. If a default value is given, then the option parameter is optional, and
+ * the given default value is used if it is not provided. If the default value is not set, and the
+ * injection site is {@code Nullable}, then the option parameter is optional, and {@code null} is
+ * used if it is not provided. Otherwise, the option parameter is required.
+ * 
+ * <p>
+ * The annotated element must be one of the following types:
+ * 
+ * <ul>
+ * <li>{@link String}</li>
+ * <li>Any primitive type</li>
+ * <li>Any boxed primitive type</li>
+ * <li>Any class or interface {@code T} with a method {@code public static T valueOf(String)}</li>
+ * <li>Any class or interface {@code T} with a method
+ * {@code public static T fromString(String)}</li>
+ * <li>Any class or interface {@code T} with a constructor {@code public T(String)}</li>
+ * </ul>
+ * 
+ * <p>
+ * Any or all of {@link #shortName()} and {@link #longName()} may be set, but at least one must be
+ * set.
+ * 
+ */
 @javax.inject.Qualifier
 @jakarta.inject.Qualifier
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
 public @interface CliOptionParameter {
   public static final String DEFAULT_VALUE_NOT_SET = "__UNDEFINED__";
 
+  /**
+   * The short name (e.g., {@code -x}, {@code -y}) of the option parameter. If not set, then the
+   * {@link #longName() long name} must be set, and the option parameter is only accessible by the
+   * long name.
+   */
   public char shortName() default '\0';
 
+  /**
+   * The long name (e.g., {@code --foo}, {@code --bar}) of the option parameter. If not set, then
+   * the {@link #shortName() short name} must be set, and the option parameter is only accessible by
+   * the short name.
+   */
   public String longName() default "";
 
+  /**
+   * The optional default value to use if the option parameter is not provided.
+   */
   public String defaultValue() default DEFAULT_VALUE_NOT_SET;
 }

rapier-cli/src/main/java/rapier/cli/CliPositionalParameter.java

@@ -24,14 +24,42 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Indicates an injection site should be populated with the value of the given positional parameter
+ * in the program arguments. If a default value is given, then the positional parameter is optional,
+ * and the given default value is used if it is not provided. If the default value is not set, and
+ * the injection site is {@code Nullable}, then the positional parameter is optional, and
+ * {@code null} is used if it is not provided. Otherwise, the positional parameter is required.
+ * 
+ * <p>
+ * The annotated element must be one of the following types:
+ * 
+ * <ul>
+ * <li>{@link String}</li>
+ * <li>Any primitive type</li>
+ * <li>Any boxed primitive type</li>
+ * <li>Any class or interface {@code T} with a method {@code public static T valueOf(String)}</li>
+ * <li>Any class or interface {@code T} with a method
+ * {@code public static T fromString(String)}</li>
+ * <li>Any class or interface {@code T} with a constructor {@code public T(String)}</li>
+ * </ul>
+ * 
+ */
 @javax.inject.Qualifier
 @jakarta.inject.Qualifier
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
 public @interface CliPositionalParameter {
   public static final String DEFAULT_VALUE_NOT_SET = "__UNDEFINED__";
 
+  /**
+   * The index of the positional parameter in the program arguments. The first positional parameter
+   * has an index of {@code 0}.
+   */
   public int value();
 
+  /**
+   * The optional default value to use if the positional parameter is not provided.
+   */
   public String defaultValue() default DEFAULT_VALUE_NOT_SET;
 }

rapier-environment-variable/src/main/java/rapier/envvar/EnvironmentVariable.java

@@ -25,11 +25,10 @@
 import java.lang.annotation.Target;
 
 /**
- * An annotation that indicates an injection site should be populated with the value of the given
+ * Indicates an injection site should be populated with the value of the given
  * {@link System#getenv() environment variable}. The value of the environment variable is read at
- * runtime and injected into the annotated element. If the environment variable is not set, the
- * default value is used instead, if given. If no default value is given, then the value is
- * {@code null}.
+ * runtime. If the environment variable is not set, then the default value is used instead, if
+ * given. If no default value is given, then the value is {@code null}.
  * 
  * <p>
  * The annotated element must be one of the following types:

rapier-system-property/src/main/java/rapier/sysprop/SystemProperty.java

@@ -25,10 +25,10 @@
 import java.lang.annotation.Target;
 
 /**
- * An annotation that indicates an injection site should be populated with the value of the given
+ * Indicates an injection site should be populated with the value of the given
  * {@link System#getProperties() system property}. The value of the system property is read at
- * runtime and injected into the annotated element. If the system property is not set, the default
- * value is used instead, if given. If no default value is given, then the value is {@code null}.
+ * runtime. If the system property is not set, then the default value is used instead, if given. If
+ * no default value is given, then the value is {@code null}.
  * 
  * <p>
  * The annotated element must be one of the following types: