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/bool.yml

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

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

@@ -32,6 +32,16 @@ EXAMPLES: |
   # items => [ { "key": "a", "value": 1 }, { "key": "b", "value": 2 } ]
   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/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/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"