Docs: Improve documentation for variables without value (#390)

README.md

@@ -180,6 +180,20 @@ second line"
 FOO="first line\nsecond line"
 ```
 
+### Variable without a value
+
+A variable can have no value:
+
+```bash
+FOO
+```
+
+It results in `dotenv_values` associating that variable name with the value `None` (e.g.
+`{"FOO": None}`. `load_dotenv`, on the other hand, simply ignores such variables.
+
+This shouldn't be confused with `FOO=`, in which case the variable is associated with the
+empty string.
+
 ### Variable expansion
 
 Python-dotenv can interpolate variables using POSIX variable expansion.

src/dotenv/main.py

@@ -351,14 +351,20 @@ def dotenv_values(
     """
     Parse a .env file and return its content as a dict.
 
-    - *dotenv_path*: absolute or relative path to .env file.
-    - *stream*: `StringIO` object with .env content, used if `dotenv_path` is `None`.
-    - *verbose*: whether to output a warning the .env file is missing. Defaults to
+    The returned dict will have `None` values for keys without values in the .env file.
+    For example, `foo=bar` results in `{"foo": "bar"}` whereas `foo` alone results in
+    `{"foo": None}`
+
+    Parameters:
+
+    - `dotenv_path`: absolute or relative path to the .env file.
+    - `stream`: `StringIO` object with .env content, used if `dotenv_path` is `None`.
+    - `verbose`: whether to output a warning if the .env file is missing. Defaults to
       `False`.
-      in `.env` file.  Defaults to `False`.
-    - *encoding*: encoding to be used to read the file.
+    - `encoding`: encoding to be used to read the file. Defaults to `"utf-8"`.
 
-    If both `dotenv_path` and `stream`, `find_dotenv()` is used to find the .env file.
+    If both `dotenv_path` and `stream` are `None`, `find_dotenv()` is used to find the
+    .env file.
     """
     if dotenv_path is None and stream is None:
         dotenv_path = find_dotenv()