filter: fix documentation (#81113)

* Updated urldecode documentation
* Misc typo fixes
* Better formatting
* Corrected some example

Fixes: #81112

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/plugins/filter/b64decode.yml

@@ -21,7 +21,7 @@ EXAMPLES: |
   lola: "{{ 'bG9sYQ==' | b64decode }}"
 
   # b64 decode the content of 'b64stuff' variable
-  stuff: "{{ b64stuff | b64encode }}"
+  stuff: "{{ b64stuff | b64decode }}"
 
 RETURN:
   _value:

lib/ansible/plugins/filter/b64encode.yml

@@ -14,10 +14,10 @@ DOCUMENTATION:
 
 EXAMPLES: |
   # b64 encode a string
-  b64lola: "{{ 'lola'|b64encode }}"
+  b64lola: "{{ 'lola'| b64encode }}"
 
   # b64 encode the content of 'stuff' variable
-  b64stuff: "{{ stuff|b64encode }}"
+  b64stuff: "{{ stuff | b64encode }}"
 
 RETURN:
   _value:

lib/ansible/plugins/filter/bool.yml

@@ -13,10 +13,10 @@ DOCUMENTATION:
 
 EXAMPLES: |
 
-  # simply encrypt my key in a vault
+  # in vars
   vars:
-    isbool: "{{ (a == b)|bool }} "
+    isbool: "{{ (a == b) | bool }} "
-    otherbool: "{{ anothervar|bool }} "
+    otherbool: "{{ anothervar | bool }} "
 
   # in a task
   ...

lib/ansible/plugins/filter/commonpath.yml

@@ -16,7 +16,8 @@ DOCUMENTATION:
       plugin_type: filter
 EXAMPLES: |
 
-  # To get the longest common path (ex. '/foo/bar') from the given list of paths (ex. ['/foo/bar/foobar','/foo/bar'])
+  # To get the longest common path (for example - '/foo/bar') from the given list of paths
+  # (for example - ['/foo/bar/foobar','/foo/bar'])
   {{ listofpaths | commonpath }}
 
 RETURN:

lib/ansible/plugins/filter/dict2items.yml

@@ -30,8 +30,18 @@ DOCUMENTATION:
 EXAMPLES: |
 
   # items => [ { "key": "a", "value": 1 }, { "key": "b", "value": 2 } ]
-  items: "{{ {'a': 1, 'b': 2}| dict2items}}"
+  items: "{{ {'a': 1, 'b': 2}| dict2items }}"
 
+  # files_dicts: [
+  #       {
+  #           "file": "users",
+  #           "path": "/etc/passwd"
+  #       },
+  #       {
+  #           "file": "groups",
+  #           "path": "/etc/group"
+  #       }
+  # ]
   vars:
     files:
       users: /etc/passwd

lib/ansible/plugins/filter/from_yaml.yml

@@ -14,7 +14,7 @@ DOCUMENTATION:
       required: true
 EXAMPLES: |
   # variable from string variable containing a YAML document
-  {{ github_workflow | from_yaml}}
+  {{ github_workflow | from_yaml }}
 
   # variable from string JSON document
   {{ '{"a": true, "b": 54, "c": [1,2,3]}' | from_yaml }}

lib/ansible/plugins/filter/from_yaml_all.yml

@@ -20,7 +20,7 @@ EXAMPLES: |
   {{ multidoc_yaml_string | from_yaml_all }}
 
   # variable from multidocument YAML string
-  {{ '---\n{"a": true, "b": 54, "c": [1,2,3]}\n...\n---{"x": 1}\n...\n' | from_yaml_all}}
+  {{ '---\n{"a": true, "b": 54, "c": [1,2,3]}\n...\n---{"x": 1}\n...\n' | from_yaml_all }}
 
 RETURN:
   _value:

lib/ansible/plugins/filter/normpath.yml

@@ -15,7 +15,7 @@ DOCUMENTATION:
       plugin_type: filter
 EXAMPLES: |
 
-  # To get a normalized path (ex. '/foo/bar') from the path (ex. '/foo//bar')
+  # To get a normalized path (for example - '/foo/bar') from the path (for example - '/foo//bar')
   {{ path | normpath }}
 
 RETURN:

lib/ansible/plugins/filter/realpath.yml

@@ -4,8 +4,8 @@ DOCUMENTATION:
   version_added: "1.8"
   short_description: Turn path into real path
   description:
-    - Resolves/follows symliknks to return the 'real path' from a given path.
+    - Resolves/follows symlinks to return the 'real path' from a given path.
-    - Filters alwasy run on controller so this path is resolved using the controller's filesystem.
+    - Filters always run on the controller so this path is resolved using the controller's filesystem.
   options:
     _input:
       description: A path.
@@ -13,6 +13,7 @@ DOCUMENTATION:
       required: true
 EXAMPLES: |
 
+  # realpath => /usr/bin/somebinary
   realpath: {{ '/path/to/synlink' | realpath }}
 
 RETURN:

lib/ansible/plugins/filter/root.yml

@@ -18,7 +18,7 @@ DOCUMENTATION:
 EXAMPLES: |
 
   # => 8
-  fiveroot: "{{ 32768 | root (5) }}"
+  fiveroot: "{{ 32768 | root(5) }}"
 
   # 2
   sqrt_of_2: "{{ 4 | root }}"

lib/ansible/plugins/filter/splitext.yml

@@ -21,7 +21,7 @@ EXAMPLES: |
   file_n_ext: "{{ 'ansible.cfg' | splitext }}"
 
   # hoax => ['/etc/hoasdf', '']
-  hoax: '{{ "/etc//hoasdf/"|splitext }}'
+  hoax: '{{ "/etc//hoasdf/" | splitext }}'
 
 RETURN:
   _value:

lib/ansible/plugins/filter/to_json.yml

@@ -58,10 +58,10 @@ DOCUMENTATION:
 
 EXAMPLES: |
   # dump variable in a template to create a JSON document
-  {{ docker_config|to_json }}
+  {{ docker_config | to_json }}
 
   # same as above but 'prettier' (equivalent to to_nice_json filter)
-  {{ docker_config|to_json(indent=4, sort_keys=True) }}
+  {{ docker_config | to_json(indent=4, sort_keys=True) }}
 
 RETURN:
   _value:

lib/ansible/plugins/filter/to_nice_json.yml

@@ -45,7 +45,7 @@ DOCUMENTATION:
 
 EXAMPLES: |
   # dump variable in a template to create a nicely formatted JSON document
-  {{ docker_config|to_nice_json }}
+  {{ docker_config | to_nice_json }}
 
 
 RETURN:

lib/ansible/plugins/filter/to_yaml.yml

@@ -41,10 +41,10 @@ DOCUMENTATION:
 
 EXAMPLES: |
   # dump variable in a template to create a YAML document
-  {{ github_workflow |to_yaml}}
+  {{ github_workflow | to_yaml }}
 
   # same as above but 'prettier' (equivalent to to_nice_yaml filter)
-  {{ docker_config|to_yaml(indent=4) }}
+  {{ docker_config | to_yaml(indent=4) }}
 
 RETURN:
   _value:

lib/ansible/plugins/filter/unvault.yml

@@ -23,12 +23,12 @@ DOCUMENTATION:
 EXAMPLES: |
   # simply decrypt my key from a vault
   vars:
-    mykey: "{{ myvaultedkey|unvault(passphrase) }} "
+    mykey: "{{ myvaultedkey | unvault(passphrase) }} "
 
   - name: save templated unvaulted data
     template: src=dump_template_data.j2 dest=/some/key/clear.txt
     vars:
-      template_data: '{{ secretdata|unvault(vaultsecret) }}'
+      template_data: '{{ secretdata | unvault(vaultsecret) }}'
 
 RETURN:
   _value:

lib/ansible/plugins/filter/urldecode.yml

@@ -1,48 +1,29 @@
 DOCUMENTATION:
-  name: urlsplit
+  name: urldecode
   version_added: "2.4"
-  short_description: get components from URL
+  short_description: Decode percent-encoded sequences
   description:
-    - Split a URL into its component parts.
+    - Replace %xx escapes with their single-character equivalent in the given string.
-  positional: _input, query
+    - Also replace plus signs with spaces, as required for unquoting HTML form values.
+  positional: _input
   options:
     _input:
-      description: URL string to split.
+      description: URL encoded string to decode.
       type: str
       required: true
-    query:
-      description: Specify a single component to return.
-      type: str
-      choices: ["fragment", "hostname", "netloc", "password",  "path",  "port",  "query", "scheme",  "username"]
 
 RETURN:
   _value:
     description:
-      - A dictionary with components as keyword and their value.
+      - URL decoded value for the given string
-      - If O(query) is provided, a string or integer will be returned instead, depending on O(query).
     type: any
 
 EXAMPLES: |
 
-    {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit }}
+    # Decode urlencoded string
-    # =>
+    {{ '%7e/abc+def' | urldecode }}
-    #   {
+    # => "~/abc def"
-    #       "fragment": "fragment",
-    #       "hostname": "www.acme.com",
-    #       "netloc": "user:password@www.acme.com:9000",
-    #       "password": "password",
-    #       "path": "/dir/index.html",
-    #       "port": 9000,
-    #       "query": "query=term",
-    #       "scheme": "http",
-    #       "username": "user"
-    #   }
-
-    {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('hostname') }}
-    # => 'www.acme.com'
-
-    {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('query') }}
-    # => 'query=term'
 
-    {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('path') }}
+    # Decode plus sign as well
-    # => '/dir/index.html'
+    {{ 'El+Ni%C3%B1o' | urldecode }}
+    # => "El Niño"