[2.14] Improve filter docs

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

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

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:

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

lib/ansible/plugins/filter/checksum.yml

@@ -13,7 +13,7 @@ DOCUMENTATION:
 
 EXAMPLES: |
     # csum => "109f4b3c50d7b0df729d299bc6f8e9ef9066971f"
-    csum : {{ 'test2' | checksum }}
+    csum: "{{ 'test2' | checksum }}"
 
 RETURN:
   _value:

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:

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:

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
 

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

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:

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.

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:

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

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:

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

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

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

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

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

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

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