Merge pull request #79 from slhck/update-docs

update docs

README.md

@@ -3,16 +3,17 @@
 ![main](https://github.com/uzzu/dotenv-gradle/workflows/main/badge.svg) [![ktlint](https://img.shields.io/badge/code%20style-%E2%9D%A4-FF4081.svg)](https://ktlint.github.io/)
 [![Gradle Plugin Portal](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/co/uzzu/dotenv/gradle/co.uzzu.dotenv.gradle.gradle.plugin/maven-metadata.xml.svg?colorB=007ec6&label=gradlePluginPortal)](https://plugins.gradle.org/plugin/co.uzzu.dotenv.gradle)
 
-**Provides a ( `.env`, `.env.template` ) variables into Project extension.**
+**Provides dotenv (`.env`) and dotenv templates (`.env.template`) as variables in a Project extension.**
 
 ## How to use
 
 ### Setup
 
-Apply this plugin to root project. This plugin is not registered to Maven Central.
-[Read the Gradle Plugin Portal to setup plugin.](https://plugins.gradle.org/plugin/co.uzzu.dotenv.gradle)
+Apply this plugin to the root project. [Read the Gradle Plugin Portal to setup the plugin.](https://plugins.gradle.org/plugin/co.uzzu.dotenv.gradle).
 
-Don't need to apply this plugin to subprojects.
+Note that this plugin is not registered to Maven Central.
+
+You do not need to apply this plugin to subprojects; the values are applied automatically.
 
 ### Create `.env` in the root directory of your gradle project
 
@@ -23,11 +24,11 @@ FOO=foo
 BAR="bar"
 BAZ='baz'
 
-# starting line comment out supported
-; starting line comment out supported
+# You can comment out lines with a #
+; You can comment out lines with a ;
 ```
 
-Then, you will be able to use environment variable into your gradle scripts.
+Then, you will be able to use the environment variables in your gradle scripts:
 
 ```Kotlin
 println(env.FOO.isPresent)              // => true
@@ -36,48 +37,50 @@ println(env.BAR.orNull())               // => bar
 println(env.BAZ.orElse("default baz"))  // => baz
 ```
 
-**Don't commit `.env` file**
+**Don't commit the `.env` file.** Ideally, add it to your `.gitignore` file.
+
+### API
+
+- `(Boolean) env.isPresent(name: String)`: Indicates that an environment variable with specified name is present.
+
+- `(String) env.fetch(name: String)`: Returns the environment variable of the given name.
+
+- `(String) env.fetch(name: String, defaultValue: String)`: Returns an environment variable, or specified default value if environment variable was not set.
 
-### Create a `.env.template` file for script completion
+- `(String?) env.fetchOrNull(name: String)`: Returns an environment variable, or `null` if the environment variable was not set.
 
-If a `.env.template` file exists, this plugin refer it to create a environemnt variable properties in the `env`
-extension.
+- `(Map<String, String) env.allVariables()`: Returns all environment variables.
 
-#### If you needed, change a template filename to read instead of `.env.template` file.
+- `(Map<String, String?) env.allVariablesOrNull()`: Returns all environment variables, and includes `null` values for unset variables.
 
-[See example](/examples/change_template_file)
+### Templates
 
-### Change a file to read instead of `.env` file.
+If a `.env.template` file exists, this plugin populates environment variables from it, too. This means you can use the template to define the environment variables that are required for your project, and optionally override them in the `.env` file.
 
-[See example](/examples/change_file)
+[See the example](/examples/change_template_file) for more details.
+
+### Changing the name of the `.env` file
+
+You can also use a different name for the `.env` file. [See this example](/examples/change_file) on how to do this.
 
 ### Hierarchical dotenv definitions
 
-Support subproject-only variables and extensions.
+This project supports subproject-only variables and extensions.
 
-[See example](/examples/hierarchical_definitions)
+[See this example](/examples/hierarchical_definitions) for more details.
 
-### Others
+### Other Features/Functions
 
-- All APIs of `env` extension consider `.env` file.
-  - If the same variable name value is defined in both the `.env` file and the system environment variable, the system
-    environment variable takes precedence.
-- `(Boolean) env.isPresent(name: String)` : Indicates an environment variable with specified name is present.
-- `(String) env.fetch(name: String)` : Returns an environment variable.
-- `(String) env.fetch(name: String, defaultValue: String)` : Returns an environment variable, or specified default value
-  if environment variable was not set.
-- `(String?) env.fetchOrNull(name: String)` : Returns an environment variable, or null if environment variable was not
-  set.
-- `(Map<String, String) env.allVariables()` : Returns all environment variables.
-- `(Map<String, String?) env.allVariablesOrNull()` : Returns all environment variables includes null values.
-- [See more examples](/examples)
+Note that all APIs of this `env` extension consider the `.env` file.
 
+If the same variable name value is defined in both the `.env` file and system environment variables, the system environment variable takes precedence.
+
+[See more examples](/examples).
 
 ## Restrictions
 
-This plugin does not support specifying properties with the -P option of CLI arguments, and there are no plans to support it in the future. See [#67](https://github.com/uzzu/dotenv-gradle/issues/67)
+This plugin does not support specifying properties with the `-P` option of CLI arguments, and there are no plans to support it in the future. See [#67](https://github.com/uzzu/dotenv-gradle/issues/67)
 
 ## License
 
 [Apache License 2.0](/LICENSE.txt)
-

examples/README.md

@@ -1,6 +1,6 @@
 ## Examples
 
 - [Basic Usage](/examples/basic)
-- [Change `.env` filename](/examples/change_file)
-- [Change `.env.template` filename](/examples/change_template_file)
+- [Example: Change the `.env` filename](/examples/change_file)
+- [Template files, changing `.env.template` filename](/examples/change_template_file)
 - [Hierarchical dotenv definitions](/examples/hierarchical_definitions)

examples/basic/README.md

@@ -1,6 +1,8 @@
-## Basic example
+## Example: Basic usage
 
-Run `./gradlew clean` and see console outputs.
+Run `./gradlew clean` and see the console outputs.
+
+This project uses a template `.env` file to define default environment variables. You can override them in the `.env` file, or specify additional ones.
 
 Edit `build.gradle.kts`, `sub/build.gradle.kts` or `.env`.
 

examples/change_file/README.md

@@ -1,19 +1,21 @@
-## Change file example
+## Example: Change the `.env` filename
 
-version since: 2.0.0
+This works with versions ≥ 2.0.0.
+
+This example shows you how to use a different name for the `.env` file. In this example, the `.env.staging` file can be used as the alternative env file. The default filename `.env` is overriden in `gradle.properties`, but commented out.
 
 Run the following command to confirm that the DotEnv file to be loaded has changed.
 
 - `./gradlew clean`
 - Edit `gradle.properties`, and `./gradlew clean`
 
-### Migrate from 1.x
+### Migrating from 1.x
 
-Change file feature by using environment variable `ENV_FILE` is removed in 2.0.0.
+In earlier versions of this plugin, the filename could be changed with the `ENV_FILE` environment variable. This is no longer possible as of version 2.0.0.
 
 Please use `dotenv.filename` in gradle.properties instead of `ENV_FILE`.
 
-----
+---
 
 ### Old spec
 

examples/change_template_file/README.md

@@ -1,9 +1,12 @@
-## Change template file example
+## Example: Template files, changing `.env.template` filename
 
-version since: 2.1.0
+This example works with versions ≥ 2.1.0.
+
+This example shows you how to use a template `.env` file, and how to change its name. In this example, the `.env.example` file is used as a template for generating the final environment. The default filanem `.env.template` is overriden in `gradle.properties`.
+
+You can see that `FOO=` is set in the `.env.example` file, and `BAZ` is set in the `.env` file.
 
 Run the following command to confirm that the DotEnv template file to be loaded has changed.
 
 - `./gradlew clean`
 - Edit `gradle.properties`, and `./gradlew clean`
-

examples/hierarchical_definitions/README.md

@@ -1,12 +1,8 @@
-## Hierarchical dotenv definitions example
+## Example: Hierarchical dotenv definitions
 
-version since: 2.0.0
+This works for version ≥ 2.0.0.
 
-The plugin until version 1.x, refers only to `.env` file in root project directory, and could not create environement
-variable extension which only to use in subproject. So organization of environment variable names makes complicated for
-a bit. (e.g. Appends prefix to name.)
-
-This feature reduces complexity of environment variable names.
+You can define environment variables in a hierarchical project. This feature reduces complexity for environment variable names in such project structures.
 
 ```
 (Root).
@@ -53,10 +49,14 @@ entire directory hierarchy is out of scope, as shown below.
         └── src
 ```
 
-Because in Gradle, the directory hierarchy only means default name of subproject. (so it can be changed)
+The reason is that in Gradle, the directory hierarchy only means default name of subproject (so it can be changed).
 
 Run `./gradlew clean` and see console outputs.
 
 Edit `build.gradle.kts`, `sub1/build.gradle.kts`, `sub2/build.gradle.kts` or each `.env` file.
 
 Then run to see if how it works.
+
+## Old Versions
+
+Note that the plugin until version 1.x referred only to an `.env` file in the root project directory, and could not create environement variable extensions which are only used in subproject.