Utility: update README.md

- Move `.env` file syntax documentation to `docs`
- Reinstate/refresh utility class summaries

Author: lkrms

docs/Env.md

@@ -0,0 +1,26 @@
+# Environment variables
+
+## `.env` file syntax
+
+Non-empty lines in a `.env` file may contain either a shell-compatible variable
+assignment (see below for limitations) or a comment.
+
+Example:
+
+```shell
+LANG=en_US.UTF-8
+TZ=Australia/Sydney
+
+# app_secret is parsed as: '^K&4nnE
+app_client_id=d8f024b9-1dfb-4dde-8f29-db98eefa317c
+app_secret=''\''^K&4nnE'
+```
+
+- Unquoted values cannot contain unescaped whitespace, `"`, `'`, `$`, backticks,
+  or glob characters (`*`, `?`, `[`, `]`).
+- Quoted values must be fully enclosed by one pair of single or double quotes.
+- Double-quoted values cannot contain `"`, `$`, or backticks unless they are
+  escaped.
+- Single-quoted values may contain single quotes if this syntax is used: `'\''`
+- Variable expansion and command substitution are not supported.
+- Comment lines must start with `#`.

src/Toolkit/Utility/Arr.php

@@ -8,6 +8,8 @@
 use Stringable;
 
 /**
+ * Work with arrays and iterables
+ *
  * @api
  */
 final class Arr extends AbstractUtility

src/Toolkit/Utility/Date.php

@@ -9,6 +9,8 @@
 use InvalidArgumentException;
 
 /**
+ * Work with date and time values, timezones and intervals
+ *
  * @api
  */
 final class Date extends AbstractUtility

src/Toolkit/Utility/Debug.php

@@ -3,6 +3,8 @@
 namespace Salient\Utility;
 
 /**
+ * Get information about the call stack
+ *
  * @api
  */
 final class Debug extends AbstractUtility

src/Toolkit/Utility/Env.php

@@ -9,32 +9,7 @@
 use RuntimeException;
 
 /**
- * Work with .env files and environment variables
- *
- * Non-empty lines in a `.env` file may contain either a shell-compatible
- * variable assignment (see below for limitations) or a comment.
- *
- * Example:
- *
- * ```shell
- * LANG=en_US.UTF-8
- * TZ=Australia/Sydney
- *
- * # app_secret is parsed as: '^K&4nnE
- * app_client_id=d8f024b9-1dfb-4dde-8f29-db98eefa317c
- * app_secret=''\''^K&4nnE'
- * ```
- *
- * - Unquoted values cannot contain unescaped whitespace, `"`, `'`, `$`,
- *   backticks, or glob characters (`*`, `?`, `[`, `]`).
- * - Quoted values must be fully enclosed by one pair of single or double
- *   quotes.
- * - Double-quoted values cannot contain `"`, `$`, or backticks unless they are
- *   escaped.
- * - Single-quoted values may contain single quotes if this syntax is used:
- *   `'\''`
- * - Variable expansion and command substitution are not supported.
- * - Comment lines must start with `#`.
+ * Work with environment variables and .env files
  *
  * {@see Env::get()}, {@see Env::getInt()}, etc. check `$_ENV`, `$_SERVER` and
  * {@see getenv()} for a given variable and return the first value found. If the

src/Toolkit/Utility/Format.php

@@ -8,7 +8,7 @@
 use JsonException;
 
 /**
- * Format data for humans
+ * Make data human-readable
  *
  * @api
  */

src/Toolkit/Utility/Inflect.php

@@ -9,7 +9,7 @@
 use Traversable;
 
 /**
- * Inflect English words
+ * Convert English words to different forms
  *
  * @api
  */

src/Toolkit/Utility/Json.php

@@ -3,7 +3,7 @@
 namespace Salient\Utility;
 
 /**
- * Wrappers for json_encode() and json_decode()
+ * Wrappers for json_encode() and json_decode() that throw exceptions on failure
  *
  * @api
  */

src/Toolkit/Utility/README.md

@@ -1,6 +1,6 @@
 # salient/utils
 
-> The utilities component of the [Salient toolkit][toolkit]
+> The utils component of the [Salient toolkit][toolkit]
 
 <p>
   <a href="https://packagist.org/packages/salient/toolkit"><img src="https://poser.pugx.org/salient/toolkit/v" alt="Latest Stable Version" /></a>
@@ -11,4 +11,64 @@
 
 ---
 
+`salient/utils` provides a suite of useful utility methods via the following
+stateless classes.
+
+- **`Arr`** works with arrays and iterables.
+
+- **`Date`** works with date and time values, timezones and intervals.
+
+- **`Debug`** gets caller information by normalising backtrace data.
+
+- **`Env`** retrieves environment variables, loads values from `.env` files, and
+  applies values from the environment to the script.
+
+- **`File`** provides methods for filesystem operations that throw exceptions on
+  failure.
+
+- **`Format`** makes data human-readable.
+
+- **`Get`** extracts, converts and generates data. For example:
+
+  - `Get::coalesce()` replicates the SQL `COALESCE()` function
+  - `Get::code()` improves upon `var_export()`
+  - `Get::copy()` gets a deep copy of an object
+  - `Get::eol()` gets a string's end-of-line sequence
+  - `Get::uuid()` generates or converts a UUID
+
+- **`Inflect`** converts English words to different forms, e.g. from singular to
+  plural.
+
+- **`Json`** provides methods for encoding and decoding JSON data that throw
+  exceptions on failure.
+
+- **`Package`** retrieves information from Composer's runtime API, e.g. the name
+  of the root package.
+
+- **`Reflect`** works with PHP's reflection API.
+
+- **`Regex`** provides methods for working with regular expressions that throw
+  exceptions on failure.
+
+- **`Str`** manipulates strings. For example:
+
+  - `Str::expandLeadingTabs()` expands leading tabs to spaces
+  - `Str::matchCase()` matches the case of one string to another
+  - `Str::ngrams()` gets a string's n-grams
+  - `Str::splitDelimited()` safely splits strings that contain delimiters
+  - `Str::toSnakeCase()` converts a string to snake_case
+
+- **`Sys`** retrieves information about the runtime environment, and provides a
+  handler for exit signals (`SIGTERM`, `SIGINT` and `SIGHUP`).
+
+- **`Test`** performs tests on values.
+
+## Documentation
+
+[API documentation][api-docs] for `salient/utils` tracks the `main` branch of
+the toolkit's [GitHub repository][toolkit], where further documentation can also
+be found.
+
+[api-docs]:
+  https://salient-labs.github.io/toolkit/namespace-Salient.Utility.html
 [toolkit]: https://github.com/salient-labs/toolkit

src/Toolkit/Utility/Regex.php

@@ -6,7 +6,8 @@
 use Stringable;
 
 /**
- * Wrappers for PHP's regular expression functions
+ * Wrappers for PHP's regular expression functions that throw exceptions on
+ * failure
  *
  * @api
  */