From 913037731fa5827a94a0f212a79b46f7852e7dad Mon Sep 17 00:00:00 2001
From: Jiri Tyr <jtyr@users.noreply.github.com>
Date: Thu, 23 Jan 2020 20:27:30 +0000
Subject: [PATCH] Update examples in documentation for env lookup plugin
 (#62662)

---
 lib/ansible/plugins/lookup/env.py | 31 ++++++++++++++++++++++++-------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/lib/ansible/plugins/lookup/env.py b/lib/ansible/plugins/lookup/env.py
index 5926bfeea47..bb0fae5f485 100644
--- a/lib/ansible/plugins/lookup/env.py
+++ b/lib/ansible/plugins/lookup/env.py
@@ -8,34 +8,51 @@ DOCUMENTATION = """
     lookup: env
     author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
     version_added: "0.9"
-    short_description: read the value of environment variables
+    short_description: Read the value of environment variables
     description:
-        - Allows you to query the environment variables available on the controller when you invoked Ansible.
+      - Allows you to query the environment variables available on the
+        controller when you invoked Ansible.
     options:
       _terms:
-        description: Environment variable or list of them to lookup the values for
+        description:
+          - Environment variable or list of them to lookup the values for.
         required: True
+    notes:
+      - The module returns an empty string if the environment variable is not
+        defined. This makes it impossbile to differentiate between the case the
+        variable is not defined and the case the variable is defined but it
+        contains an empty string.
+      - The C(default) filter requires second parameter to be set to C(True)
+        in order to set a default value in the case the variable is not
+        defined (see examples).
 """
 
 EXAMPLES = """
-- debug: msg="{{ lookup('env','HOME') }} is an environment variable"
+- name: Basic usage
+  debug:
+    msg: "'{{ lookup('env', 'HOME') }}' is the HOME environment variable."
+
+- name: Example how to set default value if the variable is not defined
+  debug:
+    msg: "'{{ lookup('env', 'USR') | default('nobody', True) }}' is the user."
 """
 
 RETURN = """
   _list:
     description:
-      - values from the environment variables.
+      - Values from the environment variables.
     type: list
 """
+
+
 from ansible.plugins.lookup import LookupBase
 from ansible.utils import py3compat
 
 
 class LookupModule(LookupBase):
-
     def run(self, terms, variables, **kwargs):
-
         ret = []
+
         for term in terms:
             var = term.split()[0]
             ret.append(py3compat.environ.get(var, ''))