From e77729fdc24102e9207bb0e91609a0a5e534cdfc Mon Sep 17 00:00:00 2001 From: Carmine DiMascio Date: Sun, 20 Sep 2020 00:43:04 -0400 Subject: [PATCH] improve javadoc --- .../io/github/cdimascio/dotenv/Dotenv.java | 36 +++++++++++++++++++ .../cdimascio/dotenv/DotenvBuilder.java | 21 +++++++---- .../github/cdimascio/dotenv/DotenvEntry.java | 11 ++++++ .../cdimascio/dotenv/DotenvException.java | 3 ++ 4 files changed, 64 insertions(+), 7 deletions(-) diff --git a/src/main/java/io/github/cdimascio/dotenv/Dotenv.java b/src/main/java/io/github/cdimascio/dotenv/Dotenv.java index 2809316..33440ca 100644 --- 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 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 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 index cd8ab5e..6fb6c0d 100644 --- a/src/main/java/io/github/cdimascio/dotenv/DotenvBuilder.java +++ b/src/main/java/io/github/cdimascio/dotenv/DotenvBuilder.java @@ -20,7 +20,8 @@ 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; @@ -28,7 +29,8 @@ public DotenvBuilder directory(String path) { } /** * 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; @@ -36,7 +38,8 @@ public DotenvBuilder filename(String name) { } /** - * 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; @@ -44,7 +47,8 @@ public DotenvBuilder ignoreIfMissing() { } /** - * 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; @@ -52,7 +56,8 @@ public DotenvBuilder ignoreIfMalformed() { } /** - * 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 envVars; private final Set set; private final Set setInFile; diff --git a/src/main/java/io/github/cdimascio/dotenv/DotenvEntry.java b/src/main/java/io/github/cdimascio/dotenv/DotenvEntry.java index 9cfad7d..7ceb172 100644 --- 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 index ac6d565..46814fb 100644 --- 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);