Various module doc fixes (#37256)

This PR includes:
- A fix for multiple-choice defaults
- A fix for messed up dictionary samples
- Cleaner defaults when they don't appear part of choices
(cherry picked from commit 80ba7b74022578e0685ea030e88821e87f28c520)

3 files changed, 74 insertions, 68 deletions

diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2
index 66a7b717fd..84bc5a4f66 100644
--- a/docs/templates/plugin.rst.j2
+++ b/docs/templates/plugin.rst.j2
@@ -107,6 +107,7 @@ Parameters
                 {# default / choices #}
                 <td>
                     <div class="cell-border">
+                        {# Recalculate choices and boolean values #}
                         {% if value.default is defined %}
                             {% if value.default == true %}
                                 {% set _x = value.update({'default': 'yes'}) %}
@@ -117,21 +118,21 @@ Parameters
                         {% if value.type == 'bool' %}
                             {% set _x = value.update({'choices': ['no', 'yes']}) %}
                         {% endif %}
+                        {# Show possible choices and highlight details #}
                         {% if value.choices %}
-                            <ul style="list-style-type: circle"><b>Choices:</b>
-                                {% if value.default not in value.choices %}
-                                    <li type="disc"><div style="color: blue"><b>@{ value.default }@</b>&nbsp;&larr;</div></li>
-                                {% endif %}
+                            <ul><b>Choices:</b>
                                 {% for choice in value.choices %}
-                                    {% if value.default is defined and choice == value.default %}
-                                        <li type="disc"><div style="color: blue"><b>@{ value.default }@</b>&nbsp;&larr;</div></li>
+                                    {% if (value.default is string and choice == value.default) or (value.default is iterable and choice in value.default) %}
+                                        <li type="disc"><div style="color: blue"><b>@{ choice | escape }@</b>&nbsp;&larr;</div></li>
                                     {% else %}
-                                        <li>@{ choice }@</li>
+                                        <li type="circle">@{ choice | escape }@</li>
                                     {% endif %}
                                 {% endfor %}
                             </ul>
-                        {% elif value.default is defined %}
-                            <div style="color: blue">@{ value.default | html_ify }@</div>
+                        {% endif %}
+                        {# Show default value, when multiple choice or no choices #}
+                        {% if value.default is defined and value.default not in value.choices %}
+                            <b>Default:</b><br/><div style="color: blue">@{ value.default | escape }@</div>
                         {% endif %}
                     </div>
                 </td>
@@ -239,8 +240,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
                 <td>
                     <div class="outer-elbow-container">
                         {% for i in range(1, loop.depth) %}
-                            <div class="elbow-placeholder">
-                            </div>
+                            <div class="elbow-placeholder"></div>
                         {% endfor %}
                         <div class="elbow-key">
                             <b>@{ key }@</b>
@@ -248,7 +248,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
                         </div>
                     </div>
                 </td>
-                <td><div class="cell-border">@{ value.returned }@</div></td>
+                <td><div class="cell-border">@{ value.returned | html_ify }@</div></td>
                 <td>
                     <div class="cell-border">
                         {% if value.description is string %}
@@ -259,10 +259,10 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
                             {% endfor %}
                         {% endif %}
                         <br/>
-                        {% if value.sample %}
+                        {% if value.sample is defined and value.sample %}
                             <div style="font-size: smaller"><b>Sample:</b></div>
-{#                            <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
-                            <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
+                            {# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #}
+                            <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | replace('\n', '\n    ') | html_ify }@</div>
                         {% endif %}
                     </div>
                 </td>
@@ -313,7 +313,7 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
                         </div>
                     </div>
                 </td>
-                <td><div class="cell-border">@{ value.returned }@</div></td>
+                <td><div class="cell-border">@{ value.returned | html_ify }@</div></td>
                 <td>
                     <div class="cell-border">
                         {% if value.description is string %}
@@ -324,10 +324,10 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
                             {% endfor %}
                         {% endif %}
                         <br/>
-                        {% if value.sample %}
+                        {% if value.sample is defined  and value.sample %}
                             <div style="font-size: smaller"><b>Sample:</b></div>
-{#                            <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
-                            <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
+                            {# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #}
+                            <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | replace('\n', '\n    ') | html_ify }@</div>
                         {% endif %}
                     </div>
                 </td>
diff --git a/lib/ansible/modules/storage/zfs/zpool_facts.py b/lib/ansible/modules/storage/zfs/zpool_facts.py
index 3063d24e7d..5fdc9b74e6 100644
--- a/lib/ansible/modules/storage/zfs/zpool_facts.py
+++ b/lib/ansible/modules/storage/zfs/zpool_facts.py
@@ -49,11 +49,63 @@ EXAMPLES = '''
 
 # Gather space usage about all imported ZFS pools
 - zpool_facts: properties='free,size'
-  debug: msg='ZFS pool {{ item.name }} has {{ item.free }} free space out of {{ item.size }}.'
+
+- debug: msg='ZFS pool {{ item.name }} has {{ item.free }} free space out of {{ item.size }}.'
   with_items: '{{ ansible_zfs_pools }}'
 '''
 
 RETURN = '''
+ansible_facts:
+    description: Dictionary containing all the detailed information about the ZFS pool facts
+    returned: always
+    type: complex
+    contains:
+        ansible_zfs_pools:
+            description: ZFS pool facts
+            returned: always
+            type: string
+            sample:
+                {
+                    "allocated": "3.46G",
+                    "altroot": "-",
+                    "autoexpand": "off",
+                    "autoreplace": "off",
+                    "bootfs": "rpool/ROOT/openindiana",
+                    "cachefile": "-",
+                    "capacity": "6%",
+                    "comment": "-",
+                    "dedupditto": "0",
+                    "dedupratio": "1.00x",
+                    "delegation": "on",
+                    "expandsize": "-",
+                    "failmode": "wait",
+                    "feature@async_destroy": "enabled",
+                    "feature@bookmarks": "enabled",
+                    "feature@edonr": "enabled",
+                    "feature@embedded_data": "active",
+                    "feature@empty_bpobj": "active",
+                    "feature@enabled_txg": "active",
+                    "feature@extensible_dataset": "enabled",
+                    "feature@filesystem_limits": "enabled",
+                    "feature@hole_birth": "active",
+                    "feature@large_blocks": "enabled",
+                    "feature@lz4_compress": "active",
+                    "feature@multi_vdev_crash_dump": "enabled",
+                    "feature@sha512": "enabled",
+                    "feature@skein": "enabled",
+                    "feature@spacemap_histogram": "active",
+                    "fragmentation": "3%",
+                    "free": "46.3G",
+                    "freeing": "0",
+                    "guid": "15729052870819522408",
+                    "health": "ONLINE",
+                    "leaked": "0",
+                    "listsnapshots": "off",
+                    "name": "rpool",
+                    "readonly": "off",
+                    "size": "49.8G",
+                    "version": "-"
+                }
 name:
     description: ZFS pool name
     returned: always
@@ -64,52 +116,6 @@ parsable:
     returned: if 'parsable' is set to True
     type: boolean
     sample: True
-zfs_pools:
-    description: ZFS pool facts
-    returned: always
-    type: string
-    sample:
-            {
-                "allocated": "3.46G",
-                "altroot": "-",
-                "autoexpand": "off",
-                "autoreplace": "off",
-                "bootfs": "rpool/ROOT/openindiana",
-                "cachefile": "-",
-                "capacity": "6%",
-                "comment": "-",
-                "dedupditto": "0",
-                "dedupratio": "1.00x",
-                "delegation": "on",
-                "expandsize": "-",
-                "failmode": "wait",
-                "feature@async_destroy": "enabled",
-                "feature@bookmarks": "enabled",
-                "feature@edonr": "enabled",
-                "feature@embedded_data": "active",
-                "feature@empty_bpobj": "active",
-                "feature@enabled_txg": "active",
-                "feature@extensible_dataset": "enabled",
-                "feature@filesystem_limits": "enabled",
-                "feature@hole_birth": "active",
-                "feature@large_blocks": "enabled",
-                "feature@lz4_compress": "active",
-                "feature@multi_vdev_crash_dump": "enabled",
-                "feature@sha512": "enabled",
-                "feature@skein": "enabled",
-                "feature@spacemap_histogram": "active",
-                "fragmentation": "3%",
-                "free": "46.3G",
-                "freeing": "0",
-                "guid": "15729052870819522408",
-                "health": "ONLINE",
-                "leaked": "0",
-                "listsnapshots": "off",
-                "name": "rpool",
-                "readonly": "off",
-                "size": "49.8G",
-                "version": "-"
-            }
 '''
 
 from collections import defaultdict
diff --git a/lib/ansible/modules/windows/win_acl.py b/lib/ansible/modules/windows/win_acl.py
index d06a3185de..3044c1a986 100644
--- a/lib/ansible/modules/windows/win_acl.py
+++ b/lib/ansible/modules/windows/win_acl.py
@@ -55,8 +55,8 @@ options:
       C(ObjectInherit).
     - For more information on the choices see MSDN InheritanceFlags enumeration
       at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx).
-    choices: [ ContainerInherit, None, ObjectInherit ]
-    default: For Leaf File, 'None'; For Directory, 'ContainerInherit, ObjectInherit';
+    - Defaults to C(ContainerInherit, ObjectInherit) for Directories.
+    choices: [ ContainerInherit, ObjectInherit ]
   propagation:
     description:
     - Propagation flag on the ACL rules.