Improve SecretSource Javadoc (#1302)

Co-authored-by: Joseph Petersen <josephp90@gmail.com>

plugin/src/main/java/io/jenkins/plugins/casc/Configurator.java

@@ -115,7 +115,7 @@ default Class getImplementedAPI() {
 
 
     /**
-     * @return list of {@link Configurator<T>}s to be considered so one can fully configure this component.
+     * @return list of {@link Configurator}s to be considered so one can fully configure this component.
      * Typically, configurator for an abstract extension point will return Configurators for available implementations.
      */
     @NonNull

plugin/src/main/java/io/jenkins/plugins/casc/SecretSource.java

@@ -20,6 +20,25 @@ public void init() {
         // NOOP
     }
 
+    /**
+     * Reveal the plaintext value of a secret.
+     *
+     * @param secret the variable reference to reveal
+     *
+     * @return the secret's value, or Optional.empty() if a recoverable error occurred. (An empty Optional will allow CasC to continue processing the resolver chain.)
+     * <p>Recoverable errors include:</p>
+     * <ul>
+     * <li>the secret was not found in the backing store</li>
+     * </ul>
+     *
+     * @throws IOException if an unrecoverable error occurred. (The exception will stop CasC processing the resolver chain.)
+     * <p>Unrecoverable errors include:</p>
+     * <ul>
+     * <li>all attempts to contact the backing store have failed (including any applicable retry strategies)</li>
+     * <li>authentication or authorization with the backing store failed</li>
+     * <li>the secret's value was not convertible to a String</li>
+     * </ul>
+     */
     public abstract Optional<String> reveal(String secret) throws IOException;
 
     public static List<SecretSource> all() {