Merge pull request #203 from Gmugra/javadoc_add_more_examples

[misc] added more examples and details in javadoc

README.md

@@ -254,7 +254,7 @@ There are three ways for dealing with properties that are not found in sources:
 
 2.  If method return type is `Optional` ->  method will return `Optional.empty()`
 
-3.  If method return type is not `Optional`, but the method do annotated with `@Default` -> method will return converted to return type deafult value.
+3.  If method return type is not `Optional`, but the method do annotated with `@Default` -> method will return converted to return type default value.
 FYI: The `@Default` annotation can't be used with a method that returns `Optional`.
 
 ### `@Config` annotation parameters

core/src/main/java/net/cactusthorn/config/core/Accessible.java

@@ -23,15 +23,30 @@
 import java.util.Set;
 
 /**
- * "config"-interface can extends this interface (directly or over super-interface)<br>
+ * {@link Config}-interface can extends this interface (directly or over super-interface)<br>
  * In this case generated class will also get methods for this interface<br>
  *
  * @author Alexei Khatskevich
  */
 public interface Accessible {
+
+    /**
+     *
+     * @return Unmodifiable {@link java.util.Set} of processed (after expanding and with prefix) keys
+     */
     Set<String> keys();
 
+    /**
+     * @param  key full key (with prefix etc.)
+     *
+     * @return already converted value by key
+     */
     Object get(String key);
 
+    /**
+     *
+     * @return Unmodifiable {@link java.util.Map} with all properties represented by child
+     * {@link net.cactusthorn.config.core.Config}-interface.
+     */
     Map<String, Object> asMap();
 }

core/src/main/java/net/cactusthorn/config/core/Config.java

@@ -43,6 +43,53 @@
  * }
  * </pre>
  *
+ * <h3>Interfaces inheritance</h3>
+ *
+ * <pre>
+ * interface MyRoot {
+ *
+ *      &#064;Key(rootVal) String value();
+ * }
+ *
+ * &#064;Config
+ * interface MyConfig extends MyRoot {
+ *
+ *      int intValue();
+ * }
+ * </pre>
+ *
+ * There is no limit to the number and "depth" of super-interfaces.<br>
+ * Interface level annotations (e.g. {@link Prefix}) on super-interfaces will be ignored.
+ *
+ * <h3>Accessible</h3>
+ *
+ * {@link Config}-interface can extends (directly or over super-interface) the interface {@link Accessible}.<br>
+ * In this case generated class will also get methods for this interface.
+ *
+ * <h3>Serializable</h3>
+ * {@link Config}-interface can extends (directly or over super-interface) {@link java.io.Serializable}.<br>
+ * In this case generated class will also get {@code private static final long serialVersionUID = 0L} attribute.<br>
+ * <br>
+ * However, the interface (as in the example later) can, optionally, contains {@code long serialVersionUID} constant.<br>
+ * If the constant is present, the value will be used for the {@code private static final long serialVersionUID} attribute
+ * in the generated class.<br>
+ * <br>
+ * <pre>
+ * &#064;Config
+ * public interface MyConfig extends java.io.Serializable {
+ *
+ *      long serialVersionUID = 100L;
+ *
+ *      String val();
+ * }
+ * </pre>
+ *
+ * <h3>Reloadable</h3>
+ *
+ * {@link Config}-interface can extends (directly or over super-interface) {@link Reloadable}.<br>
+ * In this case generated class will also get methods for this interface.<br>
+ * This is necessary to do to switch on "Periodical auto reloading" for the generated class.
+ *
  * @author Alexei Khatskevich
  */
 @Documented @Target(ElementType.TYPE) @Retention(RetentionPolicy.SOURCE) public @interface Config {

core/src/main/java/net/cactusthorn/config/core/Default.java

@@ -27,8 +27,33 @@
 import java.lang.annotation.Target;
 
 /**
- * Set default value (if property will not found in sources, the default value will be used).<br>
- * Can't be used for methods with {@link java.util.Optional} return type.<br>
+ * Set default value (if property will not found in sources, the default value will be used).
+ * <p>
+ * There are three ways for dealing with properties that are not found in sources
+ * <ul>
+ * <li>If the method return type is not {@link java.util.Optional} and the method do not annotated with @Default,
+ * the {@link net.cactusthorn.config.core.factory.ConfigFactory#create(Class)} method will throw runtime exception "property ... not found"
+ * <li>If the method return type is {@link java.util.Optional}:  method will return {@link java.util.Optional#empty()}
+ * <li>If the method return type is not {@link java.util.Optional}, but the method do annotated with @Default:
+ * method will return converted to return type default value.
+ * </ul>
+ *
+ * <h3>Warning</h3>
+ *
+ * The @Default annotation can't be used with a method that returns {@link java.util.Optional}.
+ *
+ * <h3>Example</h3>
+ *
+ * <pre>
+ * &#064;Config
+ * public interface MyConfiguration {
+ *
+ *     &#064;Default("my default value")
+ *     String value();
+ *
+ *     Optional&lt;Integer&gt; number(); //can't be annotated with &#064;Default
+ * }
+ * </pre>
  *
  * @author Alexei Khatskevich
  */

core/src/main/java/net/cactusthorn/config/core/Disable.java

@@ -37,7 +37,7 @@
  * @Prefix("app")
  * public interface MyConfiguration {
  *
- *     @Disable(PREFIX)
+ *     @Disable(Disable.Feature.PREFIX)
  *     String value();
  * }
  * </pre>

core/src/main/java/net/cactusthorn/config/core/Key.java

@@ -27,8 +27,84 @@
 import java.lang.annotation.Target;
 
 /**
- * Set property name for the method.<br>
- * If this annotation is not present method-name will be used as property name<br>
+ * Set property name associated with the method.<br>
+ * If this annotation is not present method-name will be used as property name.
+ *
+ * <h3>Example</h3>
+ *
+ * <pre>
+ * &#064;Config
+ * public interface MyConfiguration {
+ *
+ *     String value();
+ *
+ *     &#064;Key("config.super-number")
+ *     Optional&lt;Integer&gt; number();
+ * }
+ * </pre>
+ *
+ * <h3>System properties and/or environment variables</h3>
+ *
+ * <pre>
+ * &#064;Config
+ * public interface MyConfiguration {
+ *
+ *     //"env" is system-property or environment variable name
+ *     &#064;Key("{env}.host") URL host();
+ *     &#064;Key("{env}.port") int port();
+ * }
+ * </pre>
+ *
+ * This feature makes it possible to store, for example, settings for different environments in a single configuration file.
+ * e.g. (<a href="https://toml.io/en/">TOML</a>):<br>
+ * <br>
+ *
+ * <pre>
+ * host = "https://www.google.com/"
+ * port = 80
+ *
+ * [dev]
+ * host = "https://github.com/"
+ * port = 90
+ *
+ * [prod]
+ * host = "https://www.wikipedia.org/"
+ * port = 100
+ * </pre>
+ *
+ * <h4>FYI</h4>
+ *
+ * <ul>
+ * <li>If a system property or environment variable does not exist, an "empty string" will be used as the value.
+ * <li>After expanding, starting and ending dot-characters "." will be dropped.
+ * <li>After expanding, multiple dot-characters (e.g "...") inside the key name will be substituted to single ".".
+ * </ul>
+ *
+ * <br>
+ *
+ * <table border="1" summary="Expanding Examples">
+ *      <tr>
+ *          <th>system property value</th><th>key config</th><th>resulting key</th>
+ *      </tr>
+ *      <tr>
+ *          <td>dev</td><td>{env}.host</td><td>dev.host</td>
+ *      </tr>
+ *      <tr>
+ *          <td> </td><td>{env}.host</td><td>host</td>
+ *      </tr>
+ *      <tr>
+ *          <td>dev</td><td>server.{env}.host</td><td>server.dev.host</td>
+ *      </tr>
+ *      <tr>
+ *          <td> </td><td>server.{env}.host</td><td>server.host</td>
+ *      </tr>
+ *      <tr>
+ *          <td>dev</td><td>host.{env}</td><td>host.dev</td>
+ *      </tr>
+ *      <tr>
+ *          <td> </td><td>host.{env}</td><td>host</td>
+ *      </tr>
+ * </table>
  *
  * @author Alexei Khatskevich
  */

core/src/main/java/net/cactusthorn/config/core/Prefix.java

@@ -27,7 +27,29 @@
 import java.lang.annotation.Target;
 
 /**
- * Set global prefix for all property names
+ * Set global prefix for all property names.<br>
+ * The prefix will be added to the final property name with dot-character as separator.
+ *
+ * <h3>Example</h3>
+ *
+ * <pre>
+ * &#064;Config
+ * &#064;Prefix("app")
+ * public interface MyConfiguration {
+ *
+ *     &#064;Disable(Disable.Feature.PREFIX)
+ *     String value(); //related property name is "value"
+ *
+ *     &#064;Key("string")
+ *     String str(); //related property name is "app.string"
+ *
+ *     String mega(); //related property name is "app.mega"
+ * }
+ * </pre>
+ *
+ * <br>
+ *
+ * FYI: This annotation support system properties and/or environment variables in the same way as {@link Key}
  *
  * @author Alexei Khatskevich
  */

core/src/main/java/net/cactusthorn/config/core/Reloadable.java

@@ -20,15 +20,26 @@
 package net.cactusthorn.config.core;
 
 /**
- * "config"-interface can extends this interface (directly or over super-interface)<br>
+ * {@link Config}-interface can extends this interface (directly or over super-interface)<br>
  * In this case generated class will also get methods for this interface<br>
  *
  * @author Alexei Khatskevich
  */
 public interface Reloadable {
 
+    /**
+     * This method call reload sources associated with the child {@link Config}-interface<br>
+     *
+     * FYI: The method always reload not cached sources, even if they not changed.
+     */
     void reload();
 
+    /**
+     * Indicate if generated class auto-reloadable or not. By default returns {@code true}.<br>
+     * If the child {@link Config}-interface annotated with {@link Disable.Feature#AUTO_RELOAD} returns {@code false}.
+     *
+     * @return true if the generated class is auto-reloadable.
+     */
     default boolean autoReloadable() {
         return true;
     }

core/src/main/java/net/cactusthorn/config/core/Split.java

@@ -33,7 +33,7 @@
  * <br>
  * If this annotation is not present, default "splitter" is <b>,</b> (comma).
  *
- * <h3>Example</h3>
+ * <h3>Examples</h3>
  *
  * <pre>
  * &#064;Config
@@ -49,6 +49,19 @@
  * }
  * </pre>
  *
+ * <pre>
+ * &#064;Config
+ * &#064;Split(";")
+ * public interface MyConfiguration {
+ *
+ *     &#064;Default("DAYS;HOURS")
+ *     Set&lt;TimeUnit&gt; units();
+ *
+ *     &#064;Default("10000|10;20000|20") //as key-value separator can be used only | (pipe character)
+ *     Optional&lt;Map&lt;Integer, Byte&gt;&gt; theMap();
+ * }
+ * </pre>
+ *
  * @author Alexei Khatskevich
  */
 @Documented @Retention(SOURCE) @Target({TYPE, METHOD}) public @interface Split {