From c95a1c51e7158c7f2370b05b1c43a84e7ddb81af Mon Sep 17 00:00:00 2001
From: Ayodeji O <97124713+aosasona@users.noreply.github.com>
Date: Thu, 18 Jul 2024 20:53:10 +0100
Subject: [PATCH] More documentation for `env` functions

---
 src/dot_env/env.gleam | 111 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 101 insertions(+), 10 deletions(-)

diff --git a/src/dot_env/env.gleam b/src/dot_env/env.gleam
index 498b575..0f9e045 100644
--- a/src/dot_env/env.gleam
+++ b/src/dot_env/env.gleam
@@ -4,11 +4,16 @@ import gleam/string
 
 /// Set an environment variable (supports both Erlang and JavaScript targets)
 ///
-/// Example:
+/// ## Usage
+///
 /// ```gleam
 /// import dot_env/env
 ///
-/// env.set("FOO", "my value")
+/// fn main() {
+///   env.set("APP_NAME", "app")
+///
+///   Nil
+/// }
 /// ```
 ///
 @external(erlang, "dot_env_ffi", "set_env")
@@ -34,16 +39,20 @@ pub fn get(key: String) -> Result(String, String)
 
 /// Get an environment variable (supports both Erlang and JavaScript targets)
 ///
-/// Example:
+/// ## Usage
+///
 /// ```gleam
 /// import dot_env/env
 /// import gleam/io
 /// import gleam/result
 ///
-/// env.get_string("FOO")
-/// |> result.unwrap("NOT SET")
-/// |> io.println
+/// fn main() {
+///   env.get_string("APP_NAME")
+///   |> result.unwrap("app")
+///   |> io.println
+/// }
 /// ```
+///
 @external(erlang, "dot_env_ffi", "get_env")
 @external(javascript, "../dot_env_ffi.mjs", "get_env")
 pub fn get_string(key: String) -> Result(String, String)
@@ -56,23 +65,64 @@ pub fn get_or(key: String, default: String) -> String {
 }
 
 /// Get an environment variable or return a default value if it is not set
+///
+/// ## Usage
+///
+/// ```gleam
+/// import dot_env/env
+/// import gleam/io
+///
+/// fn main() {
+///   let app_name = env.get_string_or("APP_NAME", "My App")
+///   io.println(app_name)
+/// }
+/// ```
+///
 pub fn get_string_or(key: String, default: String) -> String {
   get_string(key)
   |> result.unwrap(default)
 }
 
-/// An alternative implementation of `get` that allows for chaining using `use`
+/// An alternative implementation of `get` that allows for chaining using `use` statements and for early returns.
+///
+/// ## Usage
+///
+/// ```gleam
+/// import dot_env/env
+/// import gleam/io
+///
+/// fn main() {
+///   use app_name <- env.get_then("APP_NAME")
+///   io.println(app_name)
+/// }
+/// ```
+///
 pub fn get_then(
   key: String,
-  f: fn(String) -> Result(t, String),
+  next: fn(String) -> Result(t, String),
 ) -> Result(t, String) {
   case get_string(key) {
-    Ok(value) -> f(value)
+    Ok(value) -> next(value)
     Error(err) -> Error(err)
   }
 }
 
-/// Get an environment variable as an integer
+/// Get an environment variable as an integer (this is the same as calling `get_string` and then parsing the `Ok` value)
+///
+/// ## Usage
+///
+/// ```gleam
+/// import dot_env/env
+/// import gleam/io
+/// import gleam/result
+///
+/// fn main() {
+///   env.get_int("PORT")
+///   |> result.unwrap(9000)
+///   |> io.println
+/// }
+/// ```
+///
 pub fn get_int(key: String) -> Result(Int, String) {
   use raw_value <- get_then(key)
 
@@ -83,12 +133,40 @@ pub fn get_int(key: String) -> Result(Int, String) {
 }
 
 /// Get an environment variable as an integer or return a default value if it is not set
+///
+/// ## Usage
+///
+/// ```gleam
+/// import dot_env/env
+/// import gleam/io
+///
+/// fn main() {
+///   let port = env.get_int_or("PORT", 9000)
+///   io.debug(port)
+/// }
+/// ```
+///
 pub fn get_int_or(key: String, default: Int) -> Int {
   get_int(key)
   |> result.unwrap(default)
 }
 
 /// Get an environment variable as a boolean
+///
+/// ## Usage
+///
+/// ```gleam
+/// import dot_env/env
+/// import gleam/io
+/// import gleam/result
+///
+/// fn main() {
+///   env.get_bool("IS_DEBUG")
+///   |> result.unwrap(False)
+///   |> io.println
+/// }
+/// ```
+///
 pub fn get_bool(key: String) -> Result(Bool, String) {
   use raw_value <- get_then(key)
 
@@ -105,6 +183,19 @@ pub fn get_bool(key: String) -> Result(Bool, String) {
 }
 
 /// Get an environment variable as a boolean or return a default value if it is not set
+///
+/// ## Usage
+///
+/// ```gleam
+/// import dot_env/env
+/// import gleam/io
+///
+/// fn main() {
+///   let is_debug = env.get_bool_or("IS_DEBUG", True)
+///   io.debug(is_debug)
+/// }
+/// ```
+///
 pub fn get_bool_or(key: String, default: Bool) -> Bool {
   get_bool(key)
   |> result.unwrap(default)