docs: clarify config() behavior for missing paths

Author: CharlieHelps

README.md

@@ -588,7 +588,7 @@ Dotenv exposes four functions:
 
 `config` will read your `.env` file, parse the contents, assign it to
 [`process.env`](https://nodejs.org/docs/latest/api/process.html#process_process_env),
-and return an Object with a `parsed` key containing the loaded content or an `error` key if it failed.
+and return an Object with a `parsed` key containing the loaded content (if any). If dotenv encounters an error while reading or parsing, it will also return it in an `error` key.
 
 ```js
 const result = dotenv.config()
@@ -618,6 +618,12 @@ By default, `config` will look for a file called .env in the current working dir
 
 Pass in multiple files as an array, and they will be parsed in order and combined with `process.env` (or `option.processEnv`, if set). The first value set for a variable will win, unless the `options.override` flag is set, in which case the last value set will win.  If a value already exists in `process.env` and the `options.override` flag is NOT set, no changes will be made to that value. 
 
+If a file in `options.path` cannot be read (for example, it does not exist), dotenv will continue processing subsequent paths.
+
+If one or more paths fail, dotenv will return the error from the last path in the array that failed, so `error` may be set even if other files were processed successfully.
+
+Environment variables from files that were read successfully will still be applied to `process.env` (subject to the `override` option). `parsed` will only contain variables from files that were successfully processed (or be empty if none were processed successfully).
+
 ```js  
 require('dotenv').config({ path: ['.env.local', '.env'] })
 ```

lib/main.d.ts

@@ -28,6 +28,10 @@ export interface DotenvConfigOptions {
    *
    * Specify a custom path if your file containing environment variables is located elsewhere.
    * Can also be an array of strings, specifying multiple paths.
+   * If multiple paths are provided and some cannot be read, dotenv will continue processing subsequent paths.
+   * If one or more paths fail, dotenv will return the error from the last path in the array that failed,
+   * so `error` may be set even if other files were processed successfully.
+   * Environment variables from files that were read successfully will still be applied (subject to the `override` option).
    *
    * example: `require('dotenv').config({ path: '/custom/path/to/.env' })`
    * example: `require('dotenv').config({ path: ['/path/to/first.env', '/path/to/second.env'] })`
@@ -65,6 +69,7 @@ export interface DotenvConfigOptions {
    * Default: `false`
    *
    * Override any environment variables that have already been set on your machine with values from your .env file.
+   * If multiple files have been provided in `options.path`, the override will be used as each successfully read file is combined with the next.
    *
    * example: `require('dotenv').config({ override: true })`
    */
@@ -95,7 +100,7 @@ export interface DotenvConfigOutput {
 }
 
 type DotenvError = Error & {
-  code: 
+  code:
     | 'MISSING_DATA'
     | 'INVALID_DOTENV_KEY'
     | 'NOT_FOUND_DOTENV_ENVIRONMENT'