[2.14] Improve filter docs (#78883)

(cherry picked from commit 9aa9b4eac0978f264951d1621dc95f17b5c0c0d7)

60 files changed, 290 insertions, 283 deletions

diff --git a/lib/ansible/plugins/filter/b64decode.yml b/lib/ansible/plugins/filter/b64decode.yml
index af71452fcb..6edf4abf2b 100644
--- a/lib/ansible/plugins/filter/b64decode.yml
+++ b/lib/ansible/plugins/filter/b64decode.yml
@@ -4,22 +4,22 @@ DOCUMENTATION:
   version_added: 'historical'
   short_description: Decode a base64 string
   description:
-    - Base64 decoding function
+    - Base64 decoding function.
   positional: _input
   options:
     _input:
-      description: A base64 string to decode
+      description: A base64 string to decode.
       type: string
       required: true
 
 EXAMPLES: |
   # b64 decode a string
-  lola: "{{ 'bG9sYQ=='|b64decode }}"
+  lola: "{{ 'bG9sYQ==' | b64decode }}"
 
   # b64 decode the content of 'b64stuff' variable
-  stuff: "{{ b64stuff|b64encode }}"
+  stuff: "{{ b64stuff | b64encode }}"
 
 RETURN:
   _value:
-    description: the contents of the base64 encoded string
+    description: The contents of the base64 encoded string.
     type: string
diff --git a/lib/ansible/plugins/filter/b64encode.yml b/lib/ansible/plugins/filter/b64encode.yml
index e830d655d1..14676e515d 100644
--- a/lib/ansible/plugins/filter/b64encode.yml
+++ b/lib/ansible/plugins/filter/b64encode.yml
@@ -4,11 +4,11 @@ DOCUMENTATION:
   version_added: 'historical'
   short_description: Encode a string as base64
   description:
-    - Base64 encoding function
+    - Base64 encoding function.
   positional: _input
   options:
     _input:
-      description: A string to encode
+      description: A string to encode.
       type: string
       required: true
 
@@ -21,5 +21,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: A base64 encoded string
+    description: A base64 encoded string.
     type: string
diff --git a/lib/ansible/plugins/filter/basename.yml b/lib/ansible/plugins/filter/basename.yml
index fdc3b4034a..4e868df804 100644
--- a/lib/ansible/plugins/filter/basename.yml
+++ b/lib/ansible/plugins/filter/basename.yml
@@ -7,7 +7,7 @@ DOCUMENTATION:
     - Returns the last name component of a path, what is left in the string that is not 'dirname'.
   options:
     _input:
-      description: A path
+      description: A path.
       type: path
       required: true
   seealso:
diff --git a/lib/ansible/plugins/filter/bool.yml b/lib/ansible/plugins/filter/bool.yml
index 571b122fe2..86ba35388f 100644
--- a/lib/ansible/plugins/filter/bool.yml
+++ b/lib/ansible/plugins/filter/bool.yml
@@ -3,7 +3,7 @@ DOCUMENTATION:
   version_added: "historical"
   short_description: cast into a boolean
   description:
-    - Attempt to cast the input into a boolean (C(True) or C(False)) value
+    - Attempt to cast the input into a boolean (C(True) or C(False)) value.
   positional: _input
   options:
     _input:
@@ -24,5 +24,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: The boolean resulting of casting the input expression into a C(True) or C(False) value
+    description: The boolean resulting of casting the input expression into a C(True) or C(False) value.
     type: bool
diff --git a/lib/ansible/plugins/filter/checksum.yml b/lib/ansible/plugins/filter/checksum.yml
index 9253046f2a..2f8eadd008 100644
--- a/lib/ansible/plugins/filter/checksum.yml
+++ b/lib/ansible/plugins/filter/checksum.yml
@@ -13,7 +13,7 @@ DOCUMENTATION:
 
 EXAMPLES: |
     # csum => "109f4b3c50d7b0df729d299bc6f8e9ef9066971f"
-    csum : {{ 'test2' | checksum }}
+    csum: "{{ 'test2' | checksum }}"
 
 RETURN:
   _value:
diff --git a/lib/ansible/plugins/filter/combinations.yml b/lib/ansible/plugins/filter/combinations.yml
index a2a4991bf8..a46e51e84d 100644
--- a/lib/ansible/plugins/filter/combinations.yml
+++ b/lib/ansible/plugins/filter/combinations.yml
@@ -17,7 +17,7 @@ DOCUMENTATION:
 EXAMPLES: |
 
   # combos_of_two => [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 1, 5 ], [ 2, 3 ], [ 2, 4 ], [ 2, 5 ], [ 3, 4 ], [ 3, 5 ], [ 4, 5 ] ]
-  combos_of_two:  "{{ [1,2,3,4,5] | combinations(2) }}"
+  combos_of_two: "{{ [1,2,3,4,5] | combinations(2) }}"
 
 
 RETURN:
diff --git a/lib/ansible/plugins/filter/combine.yml b/lib/ansible/plugins/filter/combine.yml
index 5cd553847e..f2f4371839 100644
--- a/lib/ansible/plugins/filter/combine.yml
+++ b/lib/ansible/plugins/filter/combine.yml
@@ -20,7 +20,7 @@ DOCUMENTATION:
       type: bool
       default: false
     list_merge:
-      describe: Behaviour when encountering list elements.
+      description: Behavior when encountering list elements.
       type: str
       default: replace
       choices:
diff --git a/lib/ansible/plugins/filter/comment.yml b/lib/ansible/plugins/filter/comment.yml
index 7c264e83a3..95a4efb08e 100644
--- a/lib/ansible/plugins/filter/comment.yml
+++ b/lib/ansible/plugins/filter/comment.yml
@@ -3,7 +3,7 @@ DOCUMENTATION:
   version_added: 'historical'
   short_description: comment out a string
   description:
-    - Use a programmign language convention to turn the string into an embeddable comment.
+    - Use programming language conventions to turn the input string into an embeddable comment.
   positional: _input, style
   options:
     _input:
@@ -25,21 +25,21 @@ DOCUMENTATION:
       description: Indicator the end of a comment block, only available for styles that support multiline comments.
       type: string
     newline:
-      description: Indicator of comment end of line, only available for styles that support multiline comments
+      description: Indicator of comment end of line, only available for styles that support multiline comments.
       type: string
       default: '\n'
     prefix:
-      description: Token to start each line inside a comment block, only available for styles that support multiline comments
+      description: Token to start each line inside a comment block, only available for styles that support multiline comments.
       type: string
     prefix_count:
-      description: Number of times to add a prefix at the start of a line, when a prefix exists and is usable
+      description: Number of times to add a prefix at the start of a line, when a prefix exists and is usable.
       type: int
       default: 1
     postfix:
-      description: Indicator of the end of each line inside a comment block, only available for styles that support multiline comments
+      description: Indicator of the end of each line inside a comment block, only available for styles that support multiline comments.
       type: string
     protfix_count:
-      description: Number of times to add a postfix at the end of a line, when a prefix exists and is usable
+      description: Number of times to add a postfix at the end of a line, when a prefix exists and is usable.
       type: int
       default: 1
 
diff --git a/lib/ansible/plugins/filter/difference.yml b/lib/ansible/plugins/filter/difference.yml
index b3237fb12f..decc811a19 100644
--- a/lib/ansible/plugins/filter/difference.yml
+++ b/lib/ansible/plugins/filter/difference.yml
@@ -7,11 +7,11 @@ DOCUMENTATION:
     - Provide a unique list of all the elements of the first list that do not appear in the second one.
   options:
     _input:
-      description: A list
+      description: A list.
       type: list
       required: true
     _second_list:
-      description: A list
+      description: A list.
       type: list
       required: true
   seealso:
@@ -31,5 +31,5 @@ EXAMPLES: |
   # => [10]
 RETURN:
   _value:
-    description: A unique list of the elements from the first list that do not appear on the 2nd
+    description: A unique list of the elements from the first list that do not appear on the second.
     type: list
diff --git a/lib/ansible/plugins/filter/dirname.yml b/lib/ansible/plugins/filter/dirname.yml
index ce7f1ffb93..52f7d5d42e 100644
--- a/lib/ansible/plugins/filter/dirname.yml
+++ b/lib/ansible/plugins/filter/dirname.yml
@@ -7,7 +7,7 @@ DOCUMENTATION:
     - Returns the 'head' component of a path, basically everything that is not the 'basename'.
   options:
     _input:
-      description: A path
+      description: A path.
       type: path
       required: true
   seealso:
diff --git a/lib/ansible/plugins/filter/expanduser.yml b/lib/ansible/plugins/filter/expanduser.yml
index 62df699741..2aff468777 100644
--- a/lib/ansible/plugins/filter/expanduser.yml
+++ b/lib/ansible/plugins/filter/expanduser.yml
@@ -2,9 +2,9 @@ DOCUMENTATION:
   name: basename
   author: ansible core team
   version_added: "1.5"
-  short_description: Returns a path with '~' translation.
+  short_description: Returns a path with C(~) translation.
   description:
-    - Translates `~` in a path to the proper user's home directory.
+    - Translates C(~) in a path to the proper user's home directory.
   options:
     _input:
       description: A string that contains a path.
diff --git a/lib/ansible/plugins/filter/extract.yml b/lib/ansible/plugins/filter/extract.yml
index 8637e00e4d..2b4989d15b 100644
--- a/lib/ansible/plugins/filter/extract.yml
+++ b/lib/ansible/plugins/filter/extract.yml
@@ -13,7 +13,7 @@ DOCUMENTATION:
       type: raw
       required: true
     contianer:
-      description: dictionary or list from which to extract a value
+      description: Dictionary or list from which to extract a value.
       type: raw
       required: true
     morekeys:
diff --git a/lib/ansible/plugins/filter/fileglob.yml b/lib/ansible/plugins/filter/fileglob.yml
index e2d2574ddc..69e8a9b2aa 100644
--- a/lib/ansible/plugins/filter/fileglob.yml
+++ b/lib/ansible/plugins/filter/fileglob.yml
@@ -2,8 +2,8 @@ DOCUMENTATION:
   name: fileglob
   short_description: explode a path glob to matching files
   description:
-    - return a list of files that matches the supplied path glob pattern
-    - filters run on the controller, so the files are matched from the controller's file system
+    - Return a list of files that matches the supplied path glob pattern.
+    - Filters run on the controller, so the files are matched from the controller's file system.
   positional: _input
   options:
     _input:
@@ -19,3 +19,4 @@ RETURN:
   _value:
     description: List of files matched.
     type: list
+    elements: string
diff --git a/lib/ansible/plugins/filter/from_json.yml b/lib/ansible/plugins/filter/from_json.yml
index 33dfc9c886..4edc2bd3d7 100644
--- a/lib/ansible/plugins/filter/from_json.yml
+++ b/lib/ansible/plugins/filter/from_json.yml
@@ -4,7 +4,7 @@ DOCUMENTATION:
   short_description: Convert JSON string into variable structure
   description:
     - Converts a JSON string representation into an equivalent structured Ansible variable.
-    - Ansible internally auto-converts JSON strings into variable structures in most contexts, this plugin is used for those contexts it doesn't.
+    - Ansible automatically converts JSON strings into variable structures in most contexts, use this plugin in contexts where automatic conversion does not happen.
   notes:
     - This filter functions as a wrapper to the Python C(json.loads) function.
   options:
diff --git a/lib/ansible/plugins/filter/from_yaml.yml b/lib/ansible/plugins/filter/from_yaml.yml
index 5bfcfcfa99..e9b1599734 100644
--- a/lib/ansible/plugins/filter/from_yaml.yml
+++ b/lib/ansible/plugins/filter/from_yaml.yml
@@ -4,9 +4,9 @@ DOCUMENTATION:
   short_description: Convert YAML string into variable structure
   description:
     - Converts a YAML string representation into an equivalent structured Ansible variable.
-    - Ansible internally auto-converts YAML strings into variable structures in most contexts, this plugin is used for those contexts it doesn't.
+    - Ansible automatically converts YAML strings into variable structures in most contexts, use this plugin in contexts where automatic conversion does not happen.
   notes:
-    - This filter functions as a wrapper to the Python pyyaml library's ``yaml.safe_load()`` function.
+    - This filter functions as a wrapper to the L(Python pyyaml library, https://pypi.org/project/PyYAML/)'s C(yaml.safe_load) function.
   options:
     _input:
       description: A YAML string.
@@ -21,5 +21,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: the variable resuliting from deserializing the YAML document.
+    description: The variable resulting from deserializing the YAML document.
     type: raw
diff --git a/lib/ansible/plugins/filter/from_yaml_all.yml b/lib/ansible/plugins/filter/from_yaml_all.yml
index a823615c09..b179f1cb85 100644
--- a/lib/ansible/plugins/filter/from_yaml_all.yml
+++ b/lib/ansible/plugins/filter/from_yaml_all.yml
@@ -7,7 +7,7 @@ DOCUMENTATION:
     - Ansible internally auto-converts YAML strings into variable structures in most contexts, but by default does not handle 'multi document' YAML files or strings.
     - If multiple YAML documents are not supplied, this is the equivalend of using C(from_yaml).
   notes:
-    - This filter functions as a wrapper to the Python ``yaml.safe_load_all()`` function, part of the pyyaml python library
+    - This filter functions as a wrapper to the Python C(yaml.safe_load_all) function, part of the L(pyyaml Python library, https://pypi.org/project/PyYAML/).
     - Possible conflicts in variable names from the mulitple documents are resolved directly by the pyyaml library.
   options:
     _input:
@@ -24,5 +24,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: the variable resuliting from deserializing the YAML documents.
+    description: The variable resulting from deserializing the YAML documents.
     type: raw
diff --git a/lib/ansible/plugins/filter/hash.yml b/lib/ansible/plugins/filter/hash.yml
index e87acc726c..0f5f315cc5 100644
--- a/lib/ansible/plugins/filter/hash.yml
+++ b/lib/ansible/plugins/filter/hash.yml
@@ -3,17 +3,17 @@ DOCUMENTATION:
   version_added: "1.9"
   short_description: hash of input data
   description:
-    - Returns a configurable hash (sha1) hash of the input data
+    - Returns a configurable hash of the input data. Uses L(SHA-1, https://en.wikipedia.org/wiki/SHA-1) by default.
   positional: _input
   options:
     _input:
-      description: data to checksum
+      description: Data to checksum.
       type: raw
       required: true
     hashtype:
       description:
-        - type of algorighim to produce the hash
-        - the list of available choices depends on the installed Python's hashlib
+        - Type of algorithm to produce the hash.
+        - The list of available choices depends on the installed Python's hashlib.
       type: string
       default: sha1
 EXAMPLES: |
@@ -24,5 +24,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: The checksum (sha1) of the input
+    description: The checksum of the input, as configured in I(hashtype).
     type: string
diff --git a/lib/ansible/plugins/filter/human_readable.yml b/lib/ansible/plugins/filter/human_readable.yml
index 95db5ccade..e3028ac549 100644
--- a/lib/ansible/plugins/filter/human_readable.yml
+++ b/lib/ansible/plugins/filter/human_readable.yml
@@ -3,32 +3,33 @@ DOCUMENTATION:
   version_added: "historical"
   short_description: Make bytes/bits human readable
   description:
-    - Convert byte or bit figures to more human readable formats
+    - Convert byte or bit figures to more human readable formats.
   positional: _input, isbits, unit
   options:
     _input:
-      description: bytes
+      description: Number of bytes, or bits. Depends on I(isbits).
       type: int
       required: true
-  isbits:
-      description: input is bits, instead of bytes
+    isbits:
+      description: Whether the input is bits, instead of bytes.
       type: bool
-  unit:
-      description: unit to force output into, if none specified the largest unit arrived at will be used
+      default: false
+    unit:
+      description: Unit to force output into. If none specified the largest unit arrived at will be used.
       type: str
       choices: [ 'Y', 'Z', 'E', 'P', 'T', 'G', 'M', 'K', 'B']
 EXAMPLES: |
 
   # size => "1.15 GB"
-  size: "{{ 1232345345|human_readable }}"
+  size: "{{ 1232345345 | human_readable }}"
 
   # size => "1.15 Gb"
-  size_bits: "{{ 1232345345|human_readable(true) }}"
+  size_bits: "{{ 1232345345 | human_readable(true) }}"
 
   # size => "1175.26 MB"
-  size_MB: "{{ 1232345345|human_readable(unit='M') }}"
+  size_MB: "{{ 1232345345 | human_readable(unit='M') }}"
 
 RETURN:
   _value:
-    description: human readable byte or bit size
+    description: Human readable byte or bit size.
     type: str
diff --git a/lib/ansible/plugins/filter/human_to_bytes.yml b/lib/ansible/plugins/filter/human_to_bytes.yml
index ea19ae95f2..f03deedb33 100644
--- a/lib/ansible/plugins/filter/human_to_bytes.yml
+++ b/lib/ansible/plugins/filter/human_to_bytes.yml
@@ -3,19 +3,19 @@ DOCUMENTATION:
   version_added: "historical"
   short_description: Get bytes from string
   description:
-    - Convert a human readable byte or bit string into a number bytes
+    - Convert a human readable byte or bit string into a number bytes.
   positional: _input, default_unit, isbits
   options:
     _input:
-      description: bytes
+      description: Human readable description of a number of bytes.
       type: int
       required: true
-  default_unit:
-      description: unit to assume when input does not specify it
+    default_unit:
+      description: Unit to assume when input does not specify it.
       type: str
       choices: ['Y', 'Z', 'E', 'P', 'T', 'G', 'M', 'K', 'B']
-  isbits:
-      description: if C(True) force to interpet only bit input, if C(False) force bytes, otherwise just use the notation to guess
+    isbits:
+      description: If C(True), force to interpret only bit input; if C(False), force bytes. Otherwise use the notation to guess.
       type: bool
 EXAMPLES: |
 
@@ -30,5 +30,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: integer representing the bytes from the input
+    description: Integer representing the bytes from the input.
     type: int
diff --git a/lib/ansible/plugins/filter/intersect.yml b/lib/ansible/plugins/filter/intersect.yml
index 4be56d2952..d811ecaaf0 100644
--- a/lib/ansible/plugins/filter/intersect.yml
+++ b/lib/ansible/plugins/filter/intersect.yml
@@ -7,11 +7,11 @@ DOCUMENTATION:
     - Provide a list with the common elements from other lists.
   options:
     _input:
-      description: A list
+      description: A list.
       type: list
       required: true
     _second_list:
-      description: A list
+      description: A list.
       type: list
       required: true
   seealso:
@@ -31,5 +31,5 @@ EXAMPLES: |
   # => [1, 2, 5, 3, 4]
 RETURN:
   _value:
-    description: A list with unique elements common to both lists, also known as a set
+    description: A list with unique elements common to both lists, also known as a set.
     type: list
diff --git a/lib/ansible/plugins/filter/items2dict.yml b/lib/ansible/plugins/filter/items2dict.yml
index d93eba92d1..1352c6742d 100644
--- a/lib/ansible/plugins/filter/items2dict.yml
+++ b/lib/ansible/plugins/filter/items2dict.yml
@@ -16,11 +16,11 @@ DOCUMENTATION:
       elements: dict
       required: true
     key_name:
-      description: The name of the key in the element dictionaries that holds the key to use at destination
+      description: The name of the key in the element dictionaries that holds the key to use at destination.
       type: str
       default: key
     value_name:
-      description: The name of the key in the element dictionaries that holds the value to use at destination
+      description: The name of the key in the element dictionaries that holds the value to use at destination.
       type: str
       default: value
   seealso:
@@ -44,5 +44,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: dictionary with the consolidated key/values
+    description: Dictionary with the consolidated key/values.
     type: dict
diff --git a/lib/ansible/plugins/filter/log.yml b/lib/ansible/plugins/filter/log.yml
index ca59696f7f..c7bb70451b 100644
--- a/lib/ansible/plugins/filter/log.yml
+++ b/lib/ansible/plugins/filter/log.yml
@@ -3,19 +3,20 @@ DOCUMENTATION:
   version_added: "1.9"
   short_description: log of (math operation)
   description:
-    - math operation that returns the N logarithim of inputed number logN(X)
+    - Math operation that returns the L(logarithm, https://en.wikipedia.org/wiki/Logarithm) to base N of the input number.
+    - By default, computes the L(natural logarithm, https://en.wikipedia.org/wiki/Natural_logarithm).
   notes:
-    - This is a passthrough to Python's C(math.log)
+    - This is a passthrough to Python's C(math.log).
   positional: _input, base
   options:
     _input:
-      description: number to operate on
-      type: int
+      description: Number to operate on.
+      type: float
       required: true
     base:
-      description: which base to use
-      type: int
-      default: 10
+      description: Which base to use. Defaults to L(Euler's number, https://en.wikipedia.org/wiki/Euler%27s_number).
+      type: float
+      default: 2.718281828459045
 
 EXAMPLES: |
 
@@ -28,5 +29,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: resulting number
-    type: int
+    description: Resulting number.
+    type: float
diff --git a/lib/ansible/plugins/filter/mandatory.yml b/lib/ansible/plugins/filter/mandatory.yml
index 878a240e53..5addf15986 100644
--- a/lib/ansible/plugins/filter/mandatory.yml
+++ b/lib/ansible/plugins/filter/mandatory.yml
@@ -1,21 +1,21 @@
 DOCUMENTATION:
   name: mandatory
   version_added: "historical"
-  short_description: make a varaible's existance mandatory
+  short_description: make a variable's existance mandatory
   description:
     - Depending on context undefined variables can be ignored or skipped, this ensures they force an error.
   positional: _input
   options:
     _input:
-      description: mandatory expression
+      description: Mandatory expression.
       type: raw
       required: true
 EXAMPLES: |
 
     # results in a Filter Error
-    {{ notdefined | mandatory}}
+    {{ notdefined | mandatory }}
 
 RETURN:
   _value:
-    description: the input if defined, otherwise an error
+    description: The input if defined, otherwise an error.
     type: raw
diff --git a/lib/ansible/plugins/filter/md5.yml b/lib/ansible/plugins/filter/md5.yml
index 02993dfd5d..c97870d086 100644
--- a/lib/ansible/plugins/filter/md5.yml
+++ b/lib/ansible/plugins/filter/md5.yml
@@ -1,12 +1,12 @@
 DOCUMENTATION:
   name: md5
   version_added: "historical"
-  short_description: md5 hash of input data
+  short_description: MD5 hash of input data
   description:
-    - Returns a md5 hash of the input data
+    - Returns an L(MD5 hash, https://en.wikipedia.org/wiki/MD5) of the input data
   positional: _input
   notes:
-    - This requires the md5 algorithim to be available on the system, security contexts like FIPS might prevent this.
+    - This requires the MD5 algorithm to be available on the system, security contexts like FIPS might prevent this.
     - MD5 has long been deemed insecure and is not recommended for security related uses.
   options:
     _input:
@@ -20,5 +20,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: The md5 hash of the input
+    description: The MD5 hash of the input.
     type: string
diff --git a/lib/ansible/plugins/filter/password_hash.yml b/lib/ansible/plugins/filter/password_hash.yml
index 37f72a2c02..d12efb4c6a 100644
--- a/lib/ansible/plugins/filter/password_hash.yml
+++ b/lib/ansible/plugins/filter/password_hash.yml
@@ -3,35 +3,35 @@ DOCUMENTATION:
   version_added: "historical"
   short_description: convert input password into password_hash
   description:
-    - Returns a password_hash of a secret
+    - Returns a password_hash of a secret.
   positional: _input
   notes:
-    - Algorithims available might be restricted by the system
+    - Algorithms available might be restricted by the system.
   options:
     _input:
-      description: secret to hash
+      description: Secret to hash.
       type: string
       required: true
     hashtype:
-      description: hashing algorithm to use
+      description: Hashing algorithm to use.
       type: string
       default: sha512
       choices: [ md5, blowfish, sha256, sha512 ]
     salt:
-      description: secret string that is used for the hashing, if none is provided a random one can be generated
+      description: Secret string that is used for the hashing, if none is provided a random one can be generated.
       type: int
     rounds:
-      description: number of encryption rounds, default varies by algorithim used
+      description: Number of encryption rounds, default varies by algorithm used.
       type: int
     ident:
-      description: no clue
-      type: string?
+      description: Algorithm identifier.
+      type: string
 
 EXAMPLES: |
     # pwdhash => "$6$/bQCntzQ7VrgVcFa$VaMkmevkY1dqrx8neaenUDlVU.6L/.ojRbrnI4ID.yBHU6XON1cB422scCiXfUL5wRucMdLgJU0Fn38uoeBni/"
-    pwdhash: "{{ 'testing' | password_hash}}"
+    pwdhash: "{{ 'testing' | password_hash }}"
 
 RETURN:
   _value:
-    description: The resulting password hash
+    description: The resulting password hash.
     type: string
diff --git a/lib/ansible/plugins/filter/permutations.yml b/lib/ansible/plugins/filter/permutations.yml
index 24083086ab..6e0202bce3 100644
--- a/lib/ansible/plugins/filter/permutations.yml
+++ b/lib/ansible/plugins/filter/permutations.yml
@@ -3,16 +3,16 @@ DOCUMENTATION:
   version_added: "historical"
   short_description: permutations from the elements of a list
   description:
-    - Create a list of the permutations of lists from the elements of a list
-    - Unlke combinations, in permutations order is significant
+    - Create a list of the permutations of lists from the elements of a list.
+    - Unlike combinations, in permutations order is significant.
   positional: _input, list_size
   options:
     _input:
-      description: elements to base the permutations on
+      description: Elements to base the permutations on.
       type: list
       required: true
     list_size:
-      description: the size of the list for each permutation
+      description: The size of the list for each permutation.
       type: int
       required: true
 
@@ -22,5 +22,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: list of permutations lists resulting from the supplied elements and list size
+    description: List of permutations lists resulting from the supplied elements and list size.
     type: list
diff --git a/lib/ansible/plugins/filter/pow.yml b/lib/ansible/plugins/filter/pow.yml
index 865951ab8b..da2fa42739 100644
--- a/lib/ansible/plugins/filter/pow.yml
+++ b/lib/ansible/plugins/filter/pow.yml
@@ -3,18 +3,18 @@ DOCUMENTATION:
   version_added: "1.9"
   short_description: power of (math operation)
   description:
-    - math operation that returns the N power of inputed number X ^ N
+    - Math operation that returns the Nth power of inputed number, C(X ^ N).
   notes:
-    - This is a passthrough to Python's C(itertools.product)
+    - This is a passthrough to Python's C(math.pow).
   positional: _input, _power
   options:
     _input:
-      description: number to power up!
-      type: int
+      description: The base.
+      type: float
       required: true
     _power:
-      description: which power to use
-      type: int
+      description: Which power (exponent) to use.
+      type: float
       required: true
 
 EXAMPLES: |
@@ -30,5 +30,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: resulting number
-    type: int
+    description: Resulting number.
+    type: float
diff --git a/lib/ansible/plugins/filter/product.yml b/lib/ansible/plugins/filter/product.yml
index 3a5b528b4f..c558e4e426 100644
--- a/lib/ansible/plugins/filter/product.yml
+++ b/lib/ansible/plugins/filter/product.yml
@@ -3,22 +3,22 @@ DOCUMENTATION:
   version_added: "historical"
   short_description: cartesian product of lists
   description:
-    - Combines two lists into one with each element being the product of the elements of the input lists
-    - this is an effective way to create 'nested loops', looping over C(listA) and C(listB) is the same as looping over C(listA|product(listB))
+    - Combines two lists into one with each element being the product of the elements of the input lists.
+    - Creates 'nested loops'. Looping over C(listA) and C(listB) is the same as looping over C(listA | product(listB)).
   notes:
     - This is a passthrough to Python's C(itertools.product)
   positional: _input, _additional_lists, repeat
   options:
     _input:
-      description: first list
+      description: First list.
       type: list
       required: true
     _additional_lists:  #TODO: *args, N possible additional lists
-      description: addional list for the product
+      description: Additional list for the product.
       type: list
       required: false
     repeat:
-      description: number of times to repeat the product against itself
+      description: Number of times to repeat the product against itself.
       default: 1
       type: int
 EXAMPLES: |
@@ -37,5 +37,6 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: list of lists of combined elements from the input lists
+    description: List of lists of combined elements from the input lists.
     type: list
+    elements: list
diff --git a/lib/ansible/plugins/filter/quote.yml b/lib/ansible/plugins/filter/quote.yml
index 08820a9a43..2d621ed065 100644
--- a/lib/ansible/plugins/filter/quote.yml
+++ b/lib/ansible/plugins/filter/quote.yml
@@ -3,21 +3,21 @@ DOCUMENTATION:
   version_added: "2.10"
   short_description: shell quoting
   description:
-    - Quote a string to safely use as in a POSIX shell
+    - Quote a string to safely use as in a POSIX shell.
   notes:
-    - This is a passthrough to Python's C(shelex.quote)
+    - This is a passthrough to Python's C(shlex.quote).
   positional: _input
   options:
     _input:
-      description: string to quote
+      description: String to quote.
       type: str
       required: true
 
-EXAMPLES:
+EXAMPLES: |
   - name: Run a shell command
     shell: echo {{ string_value | quote }}
 
 RETURN:
   _value:
-    description: quoted string
+    description: Quoted string.
     type: str
diff --git a/lib/ansible/plugins/filter/random.yml b/lib/ansible/plugins/filter/random.yml
index 4b6dd3fcb5..b72dbb292b 100644
--- a/lib/ansible/plugins/filter/random.yml
+++ b/lib/ansible/plugins/filter/random.yml
@@ -3,24 +3,22 @@ DOCUMENTATION:
   version_added: "2.6"
   short_description: random number or list item
   description:
-    - Use the intput to either select a random element of a list or generate a random number
-  notes:
-    - This is a passthrough to Python's C(shelex.quote)
+    - Use the input to either select a random element of a list or generate a random number.
   positional: _input, start, step, seed
   options:
     _input:
-      description: A number or list/sequence, if it is a number it is the top bound for random  number generation, if it is a sequence or list, the source of the random element selected
+      description: A number or list/sequence, if it is a number it is the top bound for random  number generation, if it is a sequence or list, the source of the random element selected.
       type: raw
       required: true
     start:
-      description: bottom bound for the random number/element generated
+      description: Bottom bound for the random number/element generated.
       type: int
     step:
-      description: subsets the defined range by only using this value to select the increments of it between start and end
+      description: Subsets the defined range by only using this value to select the increments of it between start and end.
       type: int
       default: 1
     seed:
-      description: if specified use a pseudo random selection instead (repeatable)
+      description: If specified use a pseudo random selection instead (repeatable).
       type: str
 
 EXAMPLES: |
@@ -33,5 +31,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: random number or list element
+    description: Random number or list element.
     type: raw
diff --git a/lib/ansible/plugins/filter/regex_escape.yml b/lib/ansible/plugins/filter/regex_escape.yml
index fba5725729..78199097db 100644
--- a/lib/ansible/plugins/filter/regex_escape.yml
+++ b/lib/ansible/plugins/filter/regex_escape.yml
@@ -3,17 +3,17 @@ DOCUMENTATION:
   version_added: "2.8"
   short_description: escape regex chars
   description:
-    - Escape special characters in a string for use in a regular expression
+    - Escape special characters in a string for use in a regular expression.
   positional: _input, re_type
   notes:
     - posix_extended is not implemented yet
   options:
     _input:
-      description: String to escape
+      description: String to escape.
       type: str
       required: true
     re_type:
-      description: Which type of escaping to use
+      description: Which type of escaping to use.
       type: str
       default: python
       choices: [python, posix_basic]
@@ -25,5 +25,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: escaped string
+    description: Escaped string.
     type: str
diff --git a/lib/ansible/plugins/filter/regex_findall.yml b/lib/ansible/plugins/filter/regex_findall.yml
index a1cea0773c..707d6fa1e9 100644
--- a/lib/ansible/plugins/filter/regex_findall.yml
+++ b/lib/ansible/plugins/filter/regex_findall.yml
@@ -3,22 +3,22 @@ DOCUMENTATION:
   version_added: "2.0"
   short_description: extract all regex matches from string
   description:
-    - Search in a string or extract all the parts of a string matching a regular expression
+    - Search in a string or extract all the parts of a string matching a regular expression.
   positional: _input, _regex
   options:
     _input:
-      description: String to match against
+      description: String to match against.
       type: str
       required: true
     _regex:
-      description: regular expression string that defines the match
+      description: Regular expression string that defines the match.
       type: str
     multiline:
-      description: search across line endings if C(True), don't if otherwise
+      description: Search across line endings if C(True), do not if otherwise.
       type: bool
       default: no
     ignorecase:
-      description: force the serach to be case insensitive if C(True), case senstitive otherwise
+      description: Force the search to be case insensitive if C(True), case sensitive otherwise.
       type: bool
       default: no
 
@@ -32,6 +32,6 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: list of matched strings
+    description: List of matched strings.
     type: list
     elements: str
diff --git a/lib/ansible/plugins/filter/regex_replace.yml b/lib/ansible/plugins/filter/regex_replace.yml
index 327c2a54c5..bb9460cc28 100644
--- a/lib/ansible/plugins/filter/regex_replace.yml
+++ b/lib/ansible/plugins/filter/regex_replace.yml
@@ -3,29 +3,29 @@ DOCUMENTATION:
   version_added: "2.0"
   short_description: replace a string via regex
   description:
-    - Replace a substring defined by a regular expression with another defined by another regular expressoin based on the first match
+    - Replace a substring defined by a regular expression with another defined by another regular expressoin based on the first match.
   notes:
-    - Maps to Python's C(regex.replace)
+    - Maps to Python's C(regex.replace).
   positional: _input, _regex_match, _regex_replace
   options:
     _input:
-      description: String to match against
+      description: String to match against.
       type: str
       required: true
     _regex_match:
-      description: regular expression string that defines the match
+      description: Regular expression string that defines the match.
       type: int
       required: true
     _regex_replace:
-      description: regular expression string that defines the replacement
+      description: Regular expression string that defines the replacement.
       type: int
       required: true
     multiline:
-      description: search across line endings if C(True), don't if otherwise
+      description: Search across line endings if C(True), do not if otherwise.
       type: bool
       default: no
     ignorecase:
-      description: force the serach to be case insensitive if C(True), case senstitive otherwise
+      description: Force the search to be case insensitive if C(True), case sensitive otherwise.
       type: bool
       default: no
 
@@ -42,5 +42,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: string with substitution (or original if no match)
+    description: String with substitution (or original if no match).
     type: str
diff --git a/lib/ansible/plugins/filter/regex_search.yml b/lib/ansible/plugins/filter/regex_search.yml
index dee89ed81d..b459c93699 100644
--- a/lib/ansible/plugins/filter/regex_search.yml
+++ b/lib/ansible/plugins/filter/regex_search.yml
@@ -3,24 +3,24 @@ DOCUMENTATION:
   version_added: "2.0"
   short_description: extract regex match from string
   description:
-    - Search in a string to extract the part that matches the regular expression
+    - Search in a string to extract the part that matches the regular expression.
   notes:
-    - Maps to Python's C(regex.search)
+    - Maps to Python's C(regex.search).
   positional: _input, _regex
   options:
     _input:
-      description: String to match against
+      description: String to match against.
       type: str
       required: true
     _regex:
-      description: regular expression string that defines the match
+      description: Regular expression string that defines the match.
       type: str
     multiline:
-      description: search across line endings if C(True), don't if otherwise
+      description: Search across line endings if C(True), do not if otherwise.
       type: bool
       default: no
     ignorecase:
-      description: force the serach to be case insensitive if C(True), case senstitive otherwise
+      description: Force the search to be case insensitive if C(True), case sensitive otherwise.
       type: bool
       default: no
 
@@ -34,5 +34,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: matched string or empty string if no match
+    description: Matched string or empty string if no match.
     type: str
diff --git a/lib/ansible/plugins/filter/rekey_on_member.yml b/lib/ansible/plugins/filter/rekey_on_member.yml
index de0e02fe4e..d7470ab97e 100644
--- a/lib/ansible/plugins/filter/rekey_on_member.yml
+++ b/lib/ansible/plugins/filter/rekey_on_member.yml
@@ -3,20 +3,18 @@ DOCUMENTATION:
   version_added: "2.13"
   short_description: Rekey a list of dicts into a dict using a member
   positional: _input, '_key', duplicates
-  description: Iterate over several iterables in parallel, producing tuples with an item from each one
-  notes:
-    - This is mostly a passhtrough to Python's C(zip) function
+  description: Iterate over several iterables in parallel, producing tuples with an item from each one.
   options:
     _input:
-      description: Original dictionary
+      description: Original dictionary.
       type: dict
       required: yes
     _key:
-      description: The key to rekey
+      description: The key to rekey.
       type: str
       required: yes
     duplicates:
-      description: how to handle duplilcates
+      description: How to handle duplicates.
       type: str
       default: error
       choices: [overwrite, error]
@@ -28,5 +26,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: the resulting dictionary
+    description: The resulting dictionary.
     type: dict
diff --git a/lib/ansible/plugins/filter/relpath.yml b/lib/ansible/plugins/filter/relpath.yml
index 39177ca8f1..47611c7658 100644
--- a/lib/ansible/plugins/filter/relpath.yml
+++ b/lib/ansible/plugins/filter/relpath.yml
@@ -5,7 +5,7 @@ DOCUMENTATION:
   short_description: Make a path relative
   positional: _input, start
   description:
-    - Converts the given path to a relative path from the C(start).
+    - Converts the given path to a relative path from the I(start),
       or relative to the directory given in I(start).
   options:
     _input:
@@ -13,7 +13,7 @@ DOCUMENTATION:
       type: str
       required: true
     start:
-      description: The directory the path should be relative to. if not supplied the current working directory will be used
+      description: The directory the path should be relative to. If not supplied the current working directory will be used.
       type: str
 
 EXAMPLES: |
diff --git a/lib/ansible/plugins/filter/root.yml b/lib/ansible/plugins/filter/root.yml
index 6bc061cf70..4f52590bb8 100644
--- a/lib/ansible/plugins/filter/root.yml
+++ b/lib/ansible/plugins/filter/root.yml
@@ -3,16 +3,16 @@ DOCUMENTATION:
   version_added: "1.9"
   short_description: root of (math operation)
   description:
-    - math operation that returns the N root of inputed number X ^^ N
+    - Math operation that returns the Nth root of inputed number C(X ^^ N).
   positional: _input, base
   options:
     _input:
-      description: number to operate on
-      type: int
+      description: Number to operate on.
+      type: float
       required: true
     base:
-      description: which base to use
-      type: int
+      description: Which root to take.
+      type: float
       default: 2
 
 EXAMPLES: |
@@ -28,5 +28,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: resulting number
-    type: int
+    description: Resulting number.
+    type: float
diff --git a/lib/ansible/plugins/filter/sha1.yml b/lib/ansible/plugins/filter/sha1.yml
index 55776d86a3..f80803b4a1 100644
--- a/lib/ansible/plugins/filter/sha1.yml
+++ b/lib/ansible/plugins/filter/sha1.yml
@@ -1,16 +1,16 @@
 DOCUMENTATION:
   name: sha1
   version_added: "historical"
-  short_description: sha1 hash of input data
+  short_description: SHA-1 hash of input data
   description:
-    - Returns a sha1 hash of the input data
+    - Returns a L(SHA-1 hash, https://en.wikipedia.org/wiki/SHA-1) of the input data.
   positional: _input
   notes:
-    - This requires the md5 algorithim to be available on the system, security contexts like FIPS might prevent this.
-    - SHA1 has been deemed insecure and is not recommended for security related uses.
+    - This requires the SHA-1 algorithm to be available on the system, security contexts like FIPS might prevent this.
+    - SHA-1 has been deemed insecure and is not recommended for security related uses.
   options:
     _input:
-      description: data to hash
+      description: Data to hash.
       type: raw
       required: true
 
@@ -20,5 +20,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: The sha1 hash of the input
+    description: The SHA-1 hash of the input.
     type: string
diff --git a/lib/ansible/plugins/filter/shuffle.yml b/lib/ansible/plugins/filter/shuffle.yml
index affe2b7404..a7c3e7ed22 100644
--- a/lib/ansible/plugins/filter/shuffle.yml
+++ b/lib/ansible/plugins/filter/shuffle.yml
@@ -3,25 +3,25 @@ DOCUMENTATION:
   version_added: "2.6"
   short_description: randomize a list
   description:
-    - Take the elements of the input list and return in a random order
+    - Take the elements of the input list and return in a random order.
   positional: _input
   options:
     _input:
-      description: A number or list to randomize
+      description: A number or list to randomize.
       type: list
       elements: any
       required: true
     seed:
-      description: if specified use a pseudo random selection instead (repeatable)
+      description: If specified use a pseudo random selection instead (repeatable).
       type: str
 
-EXAMPLES:
+EXAMPLES: |
 
   randomized_list: "{{ ['a','b','c'] | shuffle}}"
   per_host_repeatable: "{{ ['a','b','c'] | shuffle(seed=inventory_hostname) }}"
 
 RETURN:
   _value:
-    description: random number or list element
+    description: Random number or list element.
     type: list
     elements: any
diff --git a/lib/ansible/plugins/filter/split.yml b/lib/ansible/plugins/filter/split.yml
index 7ba02da9a3..3e7b59ec3d 100644
--- a/lib/ansible/plugins/filter/split.yml
+++ b/lib/ansible/plugins/filter/split.yml
@@ -3,21 +3,21 @@ DOCUMENTATION:
   version_added: "historical"
   short_description: split a string into a list
   description:
-    - Using Python's text object method C(split()) we turn strings into lists via a 'spliting character'.
+    - Using Python's text object method C(split) we turn strings into lists via a 'spliting character'.
   notes:
-    - This is a passthrough to Python's C(shelex.quote)
+    - This is a passthrough to Python's C(str.split).
   positional: _input, _split_string
   options:
     _input:
-      description: A string to split
+      description: A string to split.
       type: str
       required: true
     _split_string:
-      description: a string on which to split the original
+      description: A string on which to split the original.
       type: str
       default: ' '
 
-EXAMPLES:
+EXAMPLES: |
 
     # listjojo => [ "jojo", "is", "a" ]
     listjojo: "{{ 'jojo is a' | split }}"
@@ -27,6 +27,6 @@ EXAMPLES:
 
 RETURN:
   _value:
-    description: list of substrings split from the original
+    description: List of substrings split from the original.
     type: list
     elements: str
diff --git a/lib/ansible/plugins/filter/splitext.yml b/lib/ansible/plugins/filter/splitext.yml
index 64d9662e20..ea9cbcec31 100644
--- a/lib/ansible/plugins/filter/splitext.yml
+++ b/lib/ansible/plugins/filter/splitext.yml
@@ -5,7 +5,7 @@ DOCUMENTATION:
   short_description: split a path into root and file extension
   positional: _input
   description:
-    - Returns a list of two, with the elements consisting filename root and extension
+    - Returns a list of two, with the elements consisting of filename root and extension.
   options:
     _input:
       description: A path.
diff --git a/lib/ansible/plugins/filter/strftime.yml b/lib/ansible/plugins/filter/strftime.yml
index 7a51757343..6cb8874ad5 100644
--- a/lib/ansible/plugins/filter/strftime.yml
+++ b/lib/ansible/plugins/filter/strftime.yml
@@ -3,20 +3,22 @@ DOCUMENTATION:
   version_added: "2.4"
   short_description: date formating
   description:
-    - Using Python's stftime function, take a data formating string and a date/time to create a formated date.
+    - Using Python's C(strftime) function, take a data formating string and a date/time to create a formated date.
   notes:
-    - This is a passthrough to Python's C(shelex.quote)
+    - This is a passthrough to Python's C(stftime).
   positional: _input, second, utc
   options:
     _input:
-      description: A formating string following stftime convetions
+      description:
+        - A formating string following C(stftime) conventions.
+        - See L(the Python documentation, https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior) for a reference.
       type: str
       required: true
     second:
-      description: datetime in seconds from C(epoch) to format, if not suplied C(gmttime()/localtime()) will be used
+      description: Datetime in seconds from C(epoch) to format, if not supplied C(gmttime/localtime) will be used.
       type: int
     utc:
-      description: if time supplied is in UTC
+      description: Whether time supplied is in UTC.
       type: bool
       default: false
 
@@ -39,5 +41,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: a formated date/time
+    description: A formatted date/time string.
     type: str
diff --git a/lib/ansible/plugins/filter/subelements.yml b/lib/ansible/plugins/filter/subelements.yml
index 5de9a53b2f..a2d1a9402e 100644
--- a/lib/ansible/plugins/filter/subelements.yml
+++ b/lib/ansible/plugins/filter/subelements.yml
@@ -4,19 +4,19 @@ DOCUMENTATION:
   short_description: retuns a product of a list and it's elements
   positional: _input, _subelement, skip_missing
   description:
-    - This produces a product of an object and the subelement values of that object, similar to the subelements lookup. This lets you specify individual subelements to use in a template _input
+    - This produces a product of an object and the subelement values of that object, similar to the subelements lookup. This lets you specify individual subelements to use in a template I(_input).
   options:
     _input:
-      description: Original list
+      description: Original list.
       type: list
       elements: any
       required: yes
     _subelement:
-      description: Label of property to extract from original list items
+      description: Label of property to extract from original list items.
       type: str
       required: yes
     skip_missing:
-      description: if C(True), ignore missing subelements, otherwise it is an error.
+      description: If C(True), ignore missing subelements, otherwise missing subelements generate an error.
       type: bool
       default: no
 
@@ -33,6 +33,6 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: list made of original list and product of the subelement list
+    description: List made of original list and product of the subelement list.
     type: list
     elements: any
diff --git a/lib/ansible/plugins/filter/symmetric_difference.yml b/lib/ansible/plugins/filter/symmetric_difference.yml
index 27541f6b5a..de4f3c6b39 100644
--- a/lib/ansible/plugins/filter/symmetric_difference.yml
+++ b/lib/ansible/plugins/filter/symmetric_difference.yml
@@ -2,16 +2,16 @@ DOCUMENTATION:
   name: symmetric_difference
   author: Brian Coca (@bcoca)
   version_added: "1.4"
-  short_description: different items from 2 lists
+  short_description: different items from two lists
   description:
     - Provide a unique list of all the elements unique to each list.
   options:
     _input:
-      description: A list
+      description: A list.
       type: list
       required: true
     _second_list:
-      description: A list
+      description: A list.
       type: list
       required: true
   seealso:
@@ -31,5 +31,5 @@ EXAMPLES: |
   # => [10, 11, 99]
 RETURN:
   _value:
-    description: A unique list of the elements from 2 lists that are unique to each one
+    description: A unique list of the elements from two lists that are unique to each one.
     type: list
diff --git a/lib/ansible/plugins/filter/ternary.yml b/lib/ansible/plugins/filter/ternary.yml
index 47c48d7a18..50ff767678 100644
--- a/lib/ansible/plugins/filter/ternary.yml
+++ b/lib/ansible/plugins/filter/ternary.yml
@@ -23,7 +23,7 @@ DOCUMENTATION:
       type: any
       version_added: '2.8'
   notes:
-    - vars as values are evaluated even if not returned. This is due to them being evaluated before being passed into the filter.
+    - Vars as values are evaluated even when not returned. This is due to them being evaluated before being passed into the filter.
 
 EXAMPLES: |
   # set first 10 volumes rw, rest as dp
diff --git a/lib/ansible/plugins/filter/to_datetime.yml b/lib/ansible/plugins/filter/to_datetime.yml
index d3d0af2d17..dbd476a1d8 100644
--- a/lib/ansible/plugins/filter/to_datetime.yml
+++ b/lib/ansible/plugins/filter/to_datetime.yml
@@ -1,19 +1,20 @@
 DOCUMENTATION:
   name: to_datetime
   version_added: "2.4"
-  short_description: Get datetime from string
+  short_description: Get C(datetime) from string
   description:
-    - Using the input string attempt to create a matching Python datetime object
+    - Using the input string attempt to create a matching Python C(datetime) object.
   notes:
-    - For a full list of format codes for working with python date format strings, see https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior.
+    - For a full list of format codes for working with Python date format strings, see
+      L(the Python documentation, https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior).
   positional: _input
   options:
     _input:
-      description: A string containing date time information
+      description: A string containing date time information.
       type: str
       required: true
     format:
-      description: strformat formated string that describes the expected format of the input string
+      description: C(strformat) formatted string that describes the expected format of the input string.
       type: str
 
 EXAMPLES: |
@@ -30,5 +31,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: datetime object from the represented value
+    description: C(datetime) object from the represented value.
     type: raw
diff --git a/lib/ansible/plugins/filter/to_json.yml b/lib/ansible/plugins/filter/to_json.yml
index c28dba43ab..6f32d7c7d3 100644
--- a/lib/ansible/plugins/filter/to_json.yml
+++ b/lib/ansible/plugins/filter/to_json.yml
@@ -5,7 +5,7 @@ DOCUMENTATION:
   short_description: Convert variable to JSON string
   description:
     - Converts an Ansible variable into a JSON string representation.
-    - This filter functions as a wrapper to the Python ``json.dumps()`` function.
+    - This filter functions as a wrapper to the Python C(json.dumps) function.
     - Ansible internally auto-converts JSON strings into variable structures so this plugin is used to force it into a JSON string.
   options:
     _input:
@@ -13,18 +13,18 @@ DOCUMENTATION:
       type: raw
       required: true
     vault_to_text:
-      description: Toggle to either unvault a vault or create the JSON version of a vaulted object
+      description: Toggle to either unvault a vault or create the JSON version of a vaulted object.
       type: bool
       default: True
       version_added: '2.9'
     preprocess_unsafe:
-      description: Toggle to represent unsafe values directly in JSON or create a unsafe object in JSON
+      description: Toggle to represent unsafe values directly in JSON or create a unsafe object in JSON.
       type: bool
       default: True
       version_added: '2.9'
     allow_nan:
-      description: When off, strict adherence to float value limits of the JSON spec, so C(nan), C(inf) and C(-inf) values will produce errors
-                   If on, JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity))
+      description: When C(False), strict adherence to float value limits of the JSON specifications, so C(nan), C(inf) and C(-inf) values will produce errors.
+                   When C(True), JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)).
       default: True
       type: bool
     check_circular:
@@ -32,29 +32,29 @@ DOCUMENTATION:
       default: True
       type: bool
     ensure_ascii:
-      description: Escapes all non ASCII characters
+      description: Escapes all non ASCII characters.
       default: True
       type: bool
     indent:
-      description: Number of spaces to indent python structures, mainly used for display to humans
+      description: Number of spaces to indent Python structures, mainly used for display to humans.
       default: 0
       type: integer
     separators:
       description: The C(item) and C(key) separator to be used in the serialized output,
-                   default may change depending on I(indent) and Python version
+                   default may change depending on I(indent) and Python version.
       default: "(', ', ': ')"
       type: tuple
     skipkeys:
-      description: If C(True), keys that are not basic Python types will be skipped
+      description: If C(True), keys that are not basic Python types will be skipped.
       default: False
       type: bool
     sort_keys:
-      description: Affects sorting of dictionary keys
+      description: Affects sorting of dictionary keys.
       default: False
       type: bool
   notes:
-    - Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12
-    - 'These parameters to ``json.dumps()`` will be ignored, as they are overriden internally: I(cls), I(default)'
+    - Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12.
+    - 'These parameters to C(json.dumps) will be ignored, as they are overriden internally: I(cls), I(default)'
 
 EXAMPLES: |
   # dump variable in a template to create a JSON document
@@ -65,5 +65,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: The JSON serialized string representing the variable structure inputted
+    description: The JSON serialized string representing the variable structure inputted.
     type: string
diff --git a/lib/ansible/plugins/filter/to_nice_json.yml b/lib/ansible/plugins/filter/to_nice_json.yml
index 8a804e91fc..bedc18bab5 100644
--- a/lib/ansible/plugins/filter/to_nice_json.yml
+++ b/lib/ansible/plugins/filter/to_nice_json.yml
@@ -5,26 +5,26 @@ DOCUMENTATION:
   short_description: Convert variable to 'nicely formatted' JSON string
   description:
     - Converts an Ansible variable into a 'nicely formatted' JSON string representation
-    - This filter functions as a wrapper to the Python ``json.dumps()`` function
-    - Ansible internally auto-converts JSON strings into variable structures so this plugin is used to force it into a JSON string
+    - This filter functions as a wrapper to the Python C(json.dumps) function.
+    - Ansible automatically converts JSON strings into variable structures so this plugin is used to forcibly retain a JSON string.
   options:
     _input:
-      description: A variable or expression that returns a data structure
+      description: A variable or expression that returns a data structure.
       type: raw
       required: true
     vault_to_text:
-      description: Toggle to either unvault a vault or create the JSON version of a vaulted object
+      description: Toggle to either unvault a vault or create the JSON version of a vaulted object.
       type: bool
       default: True
       version_added: '2.9'
     preprocess_unsafe:
-      description: Toggle to represent unsafe values directly in JSON or create a unsafe object in JSON
+      description: Toggle to represent unsafe values directly in JSON or create a unsafe object in JSON.
       type: bool
       default: True
       version_added: '2.9'
     allow_nan:
-      description: When off, strict adherence to float value limits of the JSON spec, so C(nan), C(inf) and C(-inf) values will produce errors
-                   If on, JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)).
+      description: When C(False), strict adherence to float value limits of the JSON specification, so C(nan), C(inf) and C(-inf) values will produce errors.
+                   When C(True), JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)).
       default: True
       type: bool
     check_circular:
@@ -32,7 +32,7 @@ DOCUMENTATION:
       default: True
       type: bool
     ensure_ascii:
-      description: Escapes all non ASCII characters
+      description: Escapes all non ASCII characters.
       default: True
       type: bool
     skipkeys:
@@ -40,8 +40,8 @@ DOCUMENTATION:
       default: False
       type: bool
   notes:
-    - Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12
-    - 'These parameters to ``json.dumps()`` will be ignored, they are overriden for internal use: I(cls), I(default), I(indent), I(separators), I(sort_keys).'
+    - Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12.
+    - 'These parameters to C(json.dumps) will be ignored, they are overriden for internal use: I(cls), I(default), I(indent), I(separators), I(sort_keys).'
 
 EXAMPLES: |
   # dump variable in a template to create a nicely formatted JSON document
@@ -50,5 +50,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: The 'nicely formatted' JSON serialized string representing the variable structure inputted
+    description: The 'nicely formatted' JSON serialized string representing the variable structure inputted.
     type: string
diff --git a/lib/ansible/plugins/filter/to_nice_yaml.yml b/lib/ansible/plugins/filter/to_nice_yaml.yml
index bafb5713f2..4677a86135 100644
--- a/lib/ansible/plugins/filter/to_nice_yaml.yml
+++ b/lib/ansible/plugins/filter/to_nice_yaml.yml
@@ -5,7 +5,7 @@ DOCUMENTATION:
   short_description: Convert variable to YAML string
   description:
     - Converts an Ansible variable into a YAML string representation.
-    - This filter functions as a wrapper to the Python pyaml library's ``yaml.dump()`` function.
+    - This filter functions as a wrapper to the L(Python PyYAML library, https://pypi.org/project/PyYAML/)'s C(yaml.dump) function.
     - Ansible internally auto-converts YAML strings into variable structures so this plugin is used to force it into a YAML string.
   positional: _input
   options:
@@ -14,10 +14,10 @@ DOCUMENTATION:
       type: raw
       required: true
     indent:
-      description: Number of spaces to indent python structures, mainly used for display to humans
+      description: Number of spaces to indent Python structures, mainly used for display to humans.
       type: integer
     sort_keys:
-      description: Affects sorting of dictionary keys
+      description: Affects sorting of dictionary keys.
       default: True
       type: bool
     #allow_unicode:
@@ -26,14 +26,14 @@ DOCUMENTATION:
     #  default: true
     #default_style=None, canonical=None, width=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None
   notes:
-    - more optoins may be available, see pyyaml docs for details
-    - 'These parameters to ``yaml.dump()`` will be ignored, as they are overriden internally: I(default_flow_style)'
+    - More options may be available, see L(PyYAML documentation, https://pyyaml.org/wiki/PyYAMLDocumentation) for details.
+    - 'These parameters to C(yaml.dump) will be ignored, as they are overriden internally: I(default_flow_style)'
 
 EXAMPLES: |
   # dump variable in a template to create a YAML document
-  {{ github_workflow |to_nice_yaml}}
+  {{ github_workflow | to_nice_yaml }}
 
 RETURN:
   _value:
-    description: The YAML serialized string representing the variable structure inputted
+    description: The YAML serialized string representing the variable structure inputted.
     type: string
diff --git a/lib/ansible/plugins/filter/to_uuid.yml b/lib/ansible/plugins/filter/to_uuid.yml
index 1c008e282d..266bf05fca 100644
--- a/lib/ansible/plugins/filter/to_uuid.yml
+++ b/lib/ansible/plugins/filter/to_uuid.yml
@@ -3,15 +3,15 @@ DOCUMENTATION:
   version_added: "2.9"
   short_description: namespaced UUID generator
   description:
-    - Use to generate namespeced Universal Unique ID
+    - Use to generate namespeced Universal Unique ID.
   positional: _input, namespace
   options:
     _input:
-      description: string to use as base fo the UUID
+      description: String to use as base fo the UUID.
       type: str
       required: true
     namespace:
-      description: UUID nsamespace to use
+      description: UUID namespace to use.
       type: str
       default: 361E6D51-FAEC-444A-9079-341386DA8E2E
 
@@ -26,5 +26,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: generated UUID
+    description: Generated UUID.
     type: string
diff --git a/lib/ansible/plugins/filter/to_yaml.yml b/lib/ansible/plugins/filter/to_yaml.yml
index f674b6e252..2e7be604a8 100644
--- a/lib/ansible/plugins/filter/to_yaml.yml
+++ b/lib/ansible/plugins/filter/to_yaml.yml
@@ -5,8 +5,8 @@ DOCUMENTATION:
   short_description: Convert variable to YAML string
   description:
     - Converts an Ansible variable into a YAML string representation.
-    - This filter functions as a wrapper to the Python pyaml library's ``yaml.dump()`` function.
-    - Ansible internally auto-converts YAML strings into variable structures so this plugin is used to force it into a YAML string.
+    - This filter functions as a wrapper to the L(Python PyYAML library, https://pypi.org/project/PyYAML/)'s C(yaml.dump) function.
+    - Ansible automatically converts YAML strings into variable structures so this plugin is used to forcibly retain a YAML string.
   positional: _input
   options:
     _input:
@@ -14,14 +14,14 @@ DOCUMENTATION:
       type: raw
       required: true
     indent:
-      description: Number of spaces to indent python structures, mainly used for display to humans
+      description: Number of spaces to indent Python structures, mainly used for display to humans.
       type: integer
     sort_keys:
-      description: Affects sorting of dictionary keys
+      description: Affects sorting of dictionary keys.
       default: True
       type: bool
   notes:
-    - more optoins may be available, see pyyaml docs for details
+    - More options may be available, see L(PyYAML documentation, https://pyyaml.org/wiki/PyYAMLDocumentation) for details.
 
     # TODO: find docs for these
     #allow_unicode:
@@ -48,5 +48,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: The YAML serialized string representing the variable structure inputted
+    description: The YAML serialized string representing the variable structure inputted.
     type: string
diff --git a/lib/ansible/plugins/filter/type_debug.yml b/lib/ansible/plugins/filter/type_debug.yml
index 8ca941f7d9..73f79466b6 100644
--- a/lib/ansible/plugins/filter/type_debug.yml
+++ b/lib/ansible/plugins/filter/type_debug.yml
@@ -4,7 +4,7 @@ DOCUMENTATION:
   version_added: "2.3"
   short_description: show input data type
   description:
-    - Returns the equivalent of Python's ``type()`` function
+    - Returns the equivalent of Python's C(type) function.
   options:
     _input:
       description: Variable or expression of which you want to determine type.
diff --git a/lib/ansible/plugins/filter/union.yml b/lib/ansible/plugins/filter/union.yml
index 504a7e5733..d7379002b8 100644
--- a/lib/ansible/plugins/filter/union.yml
+++ b/lib/ansible/plugins/filter/union.yml
@@ -4,14 +4,14 @@ DOCUMENTATION:
   version_added: "1.4"
   short_description: union of lists
   description:
-    - Provide a unique list of all the elements of 2 lists.
+    - Provide a unique list of all the elements of two lists.
   options:
     _input:
-      description: A list
+      description: A list.
       type: list
       required: true
     _second_list:
-      description: A list
+      description: A list.
       type: list
       required: true
   seealso:
@@ -31,5 +31,5 @@ EXAMPLES: |
   # => [1, 2, 5, 1, 3, 4, 10, 11, 99]
 RETURN:
   _value:
-    description: A unique list of all the elements from both lists
+    description: A unique list of all the elements from both lists.
     type: list
diff --git a/lib/ansible/plugins/filter/unique.yml b/lib/ansible/plugins/filter/unique.yml
index 15ec51f6fa..c627816b2e 100644
--- a/lib/ansible/plugins/filter/unique.yml
+++ b/lib/ansible/plugins/filter/unique.yml
@@ -7,7 +7,7 @@ DOCUMENTATION:
     - Creates a list of unique elements (a set) from the provided input list.
   options:
     _input:
-      description: A list
+      description: A list.
       type: list
       required: true
   seealso:
@@ -26,5 +26,5 @@ EXAMPLES: |
   # => [1, 2, 5, 3, 4, 10]
 RETURN:
   _value:
-    description: A list with unique elements, also known as a set
+    description: A list with unique elements, also known as a set.
     type: list
diff --git a/lib/ansible/plugins/filter/unvault.yml b/lib/ansible/plugins/filter/unvault.yml
index 98e62a0b27..96a82ca8f7 100644
--- a/lib/ansible/plugins/filter/unvault.yml
+++ b/lib/ansible/plugins/filter/unvault.yml
@@ -4,7 +4,7 @@ DOCUMENTATION:
   version_added: "2.12"
   short_description: Open an Ansible Vault
   description:
-    - Retrieve your information from an encrypted Ansible Vault
+    - Retrieve your information from an encrypted Ansible Vault.
   positional: secret
   options:
     _input:
@@ -12,11 +12,11 @@ DOCUMENTATION:
       type: string
       required: true
     secret:
-      description: Vault secret, the key that lets you open the vault
+      description: Vault secret, the key that lets you open the vault.
       type: string
       required: true
     vault_id:
-      description: Secret identifier, used internally to try to best match a secret when multiple are provided
+      description: Secret identifier, used internally to try to best match a secret when multiple are provided.
       type: string
       default: 'filter_default'
 
diff --git a/lib/ansible/plugins/filter/urldecode.yml b/lib/ansible/plugins/filter/urldecode.yml
index f63b3709b1..dd76937b6e 100644
--- a/lib/ansible/plugins/filter/urldecode.yml
+++ b/lib/ansible/plugins/filter/urldecode.yml
@@ -3,22 +3,24 @@ DOCUMENTATION:
   version_added: "2.4"
   short_description: get components from URL
   description:
-    - Given an URL, spiti it into it's component parts
+    - Split a URL into its component parts.
   positional: _input, query
   options:
     _input:
-      description: url string to split
+      description: URL string to split.
       type: str
       required: true
     query:
-      description: specify a single compoenent to return
+      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
-    type: dict
+    description:
+      - A dictionary with components as keyword and their value.
+      - If I(query) is provided, a string or integer will be returned instead, depending on I(query).
+    type: any
 
 EXAMPLES: |
 
diff --git a/lib/ansible/plugins/filter/urlsplit.py b/lib/ansible/plugins/filter/urlsplit.py
index 6e7588bc97..cce54bbbda 100644
--- a/lib/ansible/plugins/filter/urlsplit.py
+++ b/lib/ansible/plugins/filter/urlsplit.py
@@ -10,15 +10,15 @@ DOCUMENTATION = r'''
   version_added: "2.4"
   short_description: get components from URL
   description:
-    - Given an URL, spiti it into it's component parts
+    - Split a URL into its component parts.
   positional: _input, query
   options:
     _input:
-      description: url string to split
+      description: URL string to split.
       type: str
       required: true
     query:
-      description: specify a single compoenent to return
+      description: Specify a single component to return.
       type: str
       choices: ["fragment", "hostname", "netloc", "password",  "path",  "port",  "query", "scheme",  "username"]
 '''
@@ -51,8 +51,10 @@ EXAMPLES = r'''
 
 RETURN = r'''
   _value:
-    description: a dictionary with components as keyword and their value
-    type: dict
+    description:
+      - A dictionary with components as keyword and their value.
+      - If I(query) is provided, a string or integer will be returned instead, depending on I(query).
+    type: any
 '''
 
 from urllib.parse import urlsplit
diff --git a/lib/ansible/plugins/filter/vault.yml b/lib/ansible/plugins/filter/vault.yml
index 721846c871..1ad541e9d4 100644
--- a/lib/ansible/plugins/filter/vault.yml
+++ b/lib/ansible/plugins/filter/vault.yml
@@ -4,29 +4,29 @@ DOCUMENTATION:
   version_added: "2.12"
   short_description: vault your secrets
   description:
-    - Put your information into an encrypted Ansible Vault
+    - Put your information into an encrypted Ansible Vault.
   positional: secret
   options:
     _input:
-      description: data to vault
+      description: Data to vault.
       type: string
       required: true
     secret:
-      description: Vault secret, the key that lets you open the vault
+      description: Vault secret, the key that lets you open the vault.
       type: string
       required: true
     salt:
       description:
-        - Encryption salt, will be random if not provided
-        - While providing one makes the resulting encrypted string reproducible, it can lower the security of the vault
+        - Encryption salt, will be random if not provided.
+        - While providing one makes the resulting encrypted string reproducible, it can lower the security of the vault.
       type: string
     vault_id:
-      description: Secret identifier, used internally to try to best match a secret when multiple are provided
+      description: Secret identifier, used internally to try to best match a secret when multiple are provided.
       type: string
       default: 'filter_default'
     wrap_object:
       description:
-        - This toggle can force the return of an C(AnsibleVaultEncryptedUnicode) string object, when C(False), you get a simple string
+        - This toggle can force the return of an C(AnsibleVaultEncryptedUnicode) string object, when C(False), you get a simple string.
         - Mostly useful when combining with the C(to_yaml) filter to output the 'inline vault' format.
       type: bool
       default: False
@@ -44,5 +44,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: The vault string that contains the secret data (or AnsibleVaultEncryptedUnicode string object)
+    description: The vault string that contains the secret data (or C(AnsibleVaultEncryptedUnicode) string object).
     type: string
diff --git a/lib/ansible/plugins/filter/zip.yml b/lib/ansible/plugins/filter/zip.yml
index f0f875cdcf..20d7a9b9a0 100644
--- a/lib/ansible/plugins/filter/zip.yml
+++ b/lib/ansible/plugins/filter/zip.yml
@@ -3,22 +3,22 @@ DOCUMENTATION:
   version_added: "2.3"
   short_description: combine list elements
   positional: _input, _additional_lists
-  description: Iterate over several iterables in parallel, producing tuples with an item from each one
+  description: Iterate over several iterables in parallel, producing tuples with an item from each one.
   notes:
-    - This is mostly a passhtrough to Python's C(zip) function
+    - This is mostly a passhtrough to Python's C(zip) function.
   options:
     _input:
-      description: Original list
+      description: Original list.
       type: list
       elements: any
       required: yes
     _additional_lists:
-      description: Additional list(s)
+      description: Additional list(s).
       type: list
       elements: any
       required: yes
     strict:
-      description: If C(True) return an error on mismatching list length, otherwise shortest list determines output
+      description: If C(True) return an error on mismatching list length, otherwise shortest list determines output.
       type: bool
       default: no
 
@@ -38,6 +38,6 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: list of lists made of elements matching the positions of the input lists
+    description: List of lists made of elements matching the positions of the input lists.
     type: list
     elements: list
diff --git a/lib/ansible/plugins/filter/zip_longest.yml b/lib/ansible/plugins/filter/zip_longest.yml
index be25d8332d..db351b4014 100644
--- a/lib/ansible/plugins/filter/zip_longest.yml
+++ b/lib/ansible/plugins/filter/zip_longest.yml
@@ -5,23 +5,23 @@ DOCUMENTATION:
   positional: _input, _additional_lists
   description:
       - Make an iterator that aggregates elements from each of the iterables.
-        If the iterables are of uneven length, missing values are filled-in with fillvalue.
+        If the iterables are of uneven length, missing values are filled-in with I(fillvalue).
         Iteration continues until the longest iterable is exhausted.
   notes:
     - This is mostly a passhtrough to Python's C(itertools.zip_longest) function
   options:
     _input:
-      description: Original list
+      description: Original list.
       type: list
       elements: any
       required: yes
     _additional_lists:
-      description: Additional list(s)
+      description: Additional list(s).
       type: list
       elements: any
       required: yes
     fillvalue:
-      description: Filler value to add to output when one of the lists does not contain enough elements to match the others
+      description: Filler value to add to output when one of the lists does not contain enough elements to match the others.
       type: any
 
 EXAMPLES: |
@@ -31,6 +31,6 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: list of lists made of elements matching the positions of the input lists
+    description: List of lists made of elements matching the positions of the input lists.
     type: list
     elements: list