improve javadoc (#4)

cdimascio · web-flow · commit 427eceab8d6b · 2020-09-20T00:48:08.000-04:00
diff --git a/src/main/java/io/github/cdimascio/dotenv/Dotenv.java b/src/main/java/io/github/cdimascio/dotenv/Dotenv.java
@@ -5,19 +5,55 @@
 
 public interface Dotenv {
     enum EntriesFilter {
+        /**
+         * Filter matching only environment variables declared in the .env file
+         */
         DECLARED_IN_ENV_FILE
     }
 
+    /**
+     * Configures a new {@link Dotenv} instance
+     * @return a new {@link Dotenv} instance
+     */
     static DotenvBuilder configure() {
         return new DotenvBuilder();
     }
 
+    /**
+     * Creates and loads a {@link Dotenv} instance with default options
+     * @return a new {@link Dotenv} instance
+     */
     static Dotenv load() {
         return new DotenvBuilder().load();
     }
 
+    /**
+     * Returns the set of environment variables with values
+     * @return the set of {@link DotenvEntry}s for all environment variables
+     */
     Set<DotenvEntry> entries();
+
+    /**
+     * Returns the set of  {@link EntriesFilter}s matching the the filter
+     * @param filter the filter e.g. {@link EntriesFilter}
+     * @return the set of {@link DotenvEntry}s for environment variables matching the {@link EntriesFilter}
+     */
     Set<DotenvEntry> entries(EntriesFilter filter);
+
+    /**
+     * Retrieves the value of the environment variable specified by key
+     * @param key the environment variable
+     * @return the value of the environment variable
+     */
     String get(String key);
+
+    /**
+     * Retrieves the value of the environment variable specified by key.
+     * If the environment variable specified by key does not exist, then
+     * the defaut value is returned
+     * @param key the environment variable
+     * @param defaultValue the default value to return
+     * @return the value of the environment variable or default value
+     */
     String get(String key, String defaultValue);
 }
diff --git a/src/main/java/io/github/cdimascio/dotenv/DotenvBuilder.java b/src/main/java/io/github/cdimascio/dotenv/DotenvBuilder.java
@@ -20,39 +20,44 @@ public class DotenvBuilder {
 
     /**
      * Sets the directory containing the .env file
-     * @param path The path
+     * @param path the directory containing the .env file
+     * @return this {@link DotenvBuilder}
      */
     public DotenvBuilder directory(String path) {
         this.directoryPath = path;
         return this;
     }
     /**
      * Sets the name of the .env file. The default is .env
-     * @param name The filename
+     * @param name the filename
+     * @return this {@link DotenvBuilder}
      */
     public DotenvBuilder filename(String name) {
         filename = name;
         return this;
     }
 
     /**
-     * Do not throw an exception when .env is missing
+     * Does not throw an exception when .env is missing
+     * @return this {@link DotenvBuilder}
      */
     public DotenvBuilder ignoreIfMissing() {
         throwIfMissing = false;
         return this;
     }
 
     /**
-     * Do not throw an exception when .env is malformed
+     * Does not throw an exception when .env is malformed
+     * @return this {@link DotenvBuilder}
      */
     public DotenvBuilder ignoreIfMalformed() {
         throwIfMalformed = false;
         return this;
     }
 
     /**
-     * Adds environment variables into system properties
+     * Sets each environment variable as system properties
+     * @return this {@link DotenvBuilder}
      */
     public DotenvBuilder systemProperties() {
         systemProperties = true;
@@ -61,8 +66,10 @@ public DotenvBuilder systemProperties() {
 
     /**
      * Load the contents of .env into the virtual environment
+     * @return a new {@link Dotenv} instance
+     * @throws DotenvException when an error occurs
      */
-    public DotenvImpl load() throws DotenvException {
+    public Dotenv load() throws DotenvException {
         DotenvParser reader = new DotenvParser(
             new DotenvReader(directoryPath, filename),
             throwIfMissing,
@@ -74,7 +81,7 @@ public DotenvImpl load() throws DotenvException {
         return new DotenvImpl(env);
     }
 
-    public static class DotenvImpl implements Dotenv {
+    static class DotenvImpl implements Dotenv {
         private final Map<String, String> envVars;
         private final Set<DotenvEntry> set;
         private final Set<DotenvEntry> setInFile;
diff --git a/src/main/java/io/github/cdimascio/dotenv/DotenvEntry.java b/src/main/java/io/github/cdimascio/dotenv/DotenvEntry.java
@@ -1,5 +1,8 @@
 package io.github.cdimascio.dotenv;
 
+/**
+ * A key value pair representing an environment variable and its value
+ */
 public class DotenvEntry {
     private final String key;
     private final String value;
@@ -9,10 +12,18 @@ public DotenvEntry(String key, String value) {
         this.value = value;
     }
 
+    /**
+     * Returns the key for the {@link DotenvEntry}
+     * @return the key for the {@link DotenvEntry}
+     */
     public String getKey() {
         return key;
     }
 
+    /**
+     * Returns the value for the {@link DotenvEntry}
+     * @return the value for the {@link DotenvEntry}
+     */
     public String getValue() {
         return value;
     }
diff --git a/src/main/java/io/github/cdimascio/dotenv/DotenvException.java b/src/main/java/io/github/cdimascio/dotenv/DotenvException.java
@@ -1,5 +1,8 @@
 package io.github.cdimascio.dotenv;
 
+/**
+ * A dotenv exception
+ */
 public class DotenvException extends RuntimeException {
     public DotenvException(String message) {
         super(message);
