Add attributes 2/x (#75619)

* Added attribute information to more modules

 rearranged the shared data
 platform revamped
 use 'details' and avoid overriding description

Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_core.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_core.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_core.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_core.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_core.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/fail.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/debug.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/command.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/assert.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_core.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/gather_facts.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/include_vars.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/meta.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/meta.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_common_attributes.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_common_attributes.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update lib/ansible/plugins/doc_fragments/action_common_attributes.py

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

lib/ansible/modules/add_host.py

@@ -30,26 +30,33 @@ options:
     type: list
     aliases: [ group, groupname ]
 extends_documentation_fragment:
-- action_common_attributes
+  - action_common_attributes
+  - action_common_attributes.conn
+  - action_common_attributes.flow
+  - action_core
 attributes:
     action:
         support: full
-    async:
+    core:
-        support: none
+      details: While parts of this action are implemented in core, other parts are still available as normal plugins and can be partially overridden
+      support: partial
     become:
       support: none
     bypass_host_loop:
         support: full
+    bypass_task_loop:
+        support: none
     check_mode:
-        support: full
+        details: While this makes no changes to target systems the 'in memory' inventory will still be altered
+        support: partial
     connection:
         support: none
     delegation:
         support: none
-    proprietary:
+    diff_mode:
-        support: full
+        support: none
-    windows:
+    platform:
-        support: full
+        platforms: all
 notes:
 - The alias C(host) of the parameter C(name) is only available on Ansible 2.4 and newer.
 - Since Ansible 2.4, the C(inventory_dir) variable is now set to C(None) instead of the 'global inventory source',

lib/ansible/modules/apt.py

@@ -180,13 +180,14 @@ requirements:
    - python3-apt (python 3)
    - aptitude (before 2.4)
 author: "Matthew Williams (@mgwilliams)"
-extends_documentation_fragment:
+extends_documentation_fragment: action_common_attributes
-- action_common_attributes
 attributes:
     check_mode:
         support: full
     diff_mode:
         support: full
+    platform:
+        platforms: debian
 notes:
    - Three of the upgrade modes (C(full), C(safe) and its alias C(yes)) required C(aptitude) up to 2.3, since 2.4 C(apt-get) is used as a fall-back.
    - In most cases, packages installed with apt will start newly installed services by default. Most distributions have mechanisms to avoid this.

lib/ansible/modules/apt_key.py

@@ -19,11 +19,14 @@ version_added: "1.0"
 short_description: Add or remove an apt key
 description:
     - Add or remove an I(apt) key, optionally downloading it.
-extends_documentation_fragment:
+extends_documentation_fragment: action_common_attributes
-- action_common_attributes
 attributes:
     check_mode:
         support: full
+    diff_mode:
+        support: none
+    platform:
+        platforms: debian
 notes:
     - The apt-key command has been deprecated and suggests to 'manage keyring files in trusted.gpg.d instead'. See the Debian wiki for details.
       This module is kept for backwards compatiblity for systems that still use apt-key as the main way to manage apt repository keys.

lib/ansible/modules/apt_repository.py

@@ -17,16 +17,16 @@ module: apt_repository
 short_description: Add and remove APT repositories
 description:
     - Add or remove an APT repositories in Ubuntu and Debian.
-extends_documentation_fragment:
+extends_documentation_fragment: action_common_attributes
-- action_common_attributes
 attributes:
     check_mode:
         support: full
     diff_mode:
         support: full
+    platform:
+        platforms: debian
 notes:
-    - This module works on Debian, Ubuntu and their derivatives.
+    - This module supports Debian Squeeze (version 6) as well as its successors and derivatives.
-    - This module supports Debian Squeeze (version 6) as well as its successors.
 options:
     repo:
         description:

lib/ansible/modules/assemble.py

@@ -79,6 +79,14 @@ attributes:
       support: full
     async:
       support: none
+    bypass_host_loop:
+      support: none
+    check_mode:
+      support: none
+    diff_mode:
+      support: full
+    platform:
+      platforms: posix
     safe_file_operations:
       support: full
     vault:
@@ -91,9 +99,11 @@ seealso:
 author:
 - Stephen Fromm (@sfromm)
 extends_documentation_fragment:
-- action_common_attributes
+    - action_common_attributes
-- decrypt
+    - action_common_attributes.flow
-- files
+    - action_common_attributes.files
+    - decrypt
+    - files
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/assert.py

@@ -41,20 +41,29 @@ options:
     default: no
     version_added: "2.8"
 extends_documentation_fragment:
-- action_common_attributes
+  - action_common_attributes
+  - action_common_attributes.conn
+  - action_common_attributes.flow
 attributes:
     action:
         support: full
     async:
         support: none
+    become:
+        support: none
+    bypass_host_loop:
+        support: none
     connection:
         support: none
+    check_mode:
+        support: none
+    diff_mode:
+        support: none
     delegation:
         support: none
-    proprietary:
+        details: Aside from C(register) and/or in combination with C(delegate_facts), it has little effect.
-        support: full
+    platform:
-    windows:
+        platforms: all
-        support: full
 seealso:
 - module: ansible.builtin.debug
 - module: ansible.builtin.fail

lib/ansible/modules/async_status.py

@@ -31,13 +31,21 @@ options:
     default: status
 extends_documentation_fragment:
 - action_common_attributes
+- action_common_attributes.flow
 attributes:
     action:
         support: full
     async:
         support: none
-    windows:
+    check_mode:
+        support: none
+    diff_mode:
+        support: none
+    bypass_host_loop:
+        support: none
+    platform:
         support: full
+        platforms: posix, windows
 seealso:
 - ref: playbooks_async
   description: Detailed information on how to use asynchronous actions and polling.

lib/ansible/modules/blockinfile.py

@@ -91,9 +91,10 @@ notes:
   - Option I(follow) has been removed in Ansible 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense.
   - When more then one block should be handled in one file you must change the I(marker) per task.
 extends_documentation_fragment:
-- action_common_attributes
+    - action_common_attributes
-- files
+    - action_common_attributes.files
-- validate
+    - files
+    - validate
 attributes:
     check_mode:
         support: full
@@ -101,6 +102,11 @@ attributes:
         support: full
     safe_file_operations:
       support: full
+    platform:
+      support: full
+      platforms: posix
+    vault:
+      support: none
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/command.py

@@ -26,6 +26,20 @@ description:
        or use C(cmd) parameter.
      - Either a free form command or C(cmd) parameter is required, see the examples.
      - For Windows targets, use the M(ansible.windows.win_command) module instead.
+extends_documentation_fragment:
+    - action_common_attributes
+    - action_common_attributes.raw
+attributes:
+    check_mode:
+        details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds C(creates)/C(removes) options as a workaround
+        support: partial
+    diff_mode:
+        support: none
+    platform:
+      support: full
+      platforms: posix
+    raw:
+      support: full
 options:
   free_form:
     description:

lib/ansible/modules/copy.py

@@ -118,29 +118,37 @@ options:
     type: str
     version_added: '2.5'
 extends_documentation_fragment:
-- decrypt
+    - decrypt
-- files
+    - files
-- validate
+    - validate
-- action_common_attributes
+    - action_common_attributes
+    - action_common_attributes.files
+    - action_common_attributes.flow
 notes:
-- The M(ansible.builtin.copy) module recursively copy facility does not scale to lots (>hundreds) of files.
+    - The M(ansible.builtin.copy) module recursively copy facility does not scale to lots (>hundreds) of files.
 seealso:
-- module: ansible.builtin.assemble
+    - module: ansible.builtin.assemble
-- module: ansible.builtin.fetch
+    - module: ansible.builtin.fetch
-- module: ansible.builtin.file
+    - module: ansible.builtin.file
-- module: ansible.builtin.template
+    - module: ansible.builtin.template
-- module: ansible.posix.synchronize
+    - module: ansible.posix.synchronize
-- module: ansible.windows.win_copy
+    - module: ansible.windows.win_copy
 author:
-- Ansible Core Team
+    - Ansible Core Team
-- Michael DeHaan
+    - Michael DeHaan
 attributes:
   action:
     support: full
+  async:
+    support: none
+  bypass_host_loop:
+    support: none
   check_mode:
     support: full
   diff_mode:
     support: full
+  platform:
+    platforms: posix
   safe_file_operations:
       support: full
   vault:

lib/ansible/modules/cron.py

@@ -140,12 +140,15 @@ author:
   - Evan Kaufman (@EvanK)
   - Luca Berruti (@lberruti)
 extends_documentation_fragment:
-- action_common_attributes
+    - action_common_attributes
 attributes:
     check_mode:
         support: full
     diff_mode:
         support: full
+    platform:
+        support: full
+        platforms: posix
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/debconf.py

@@ -16,6 +16,16 @@ description:
      - Configure a .deb package using debconf-set-selections.
      - Or just query existing selections.
 version_added: "1.6"
+extends_documentation_fragment:
+- action_common_attributes
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: full
+    platform:
+        support: full
+        platforms: debian
 notes:
     - This module requires the command line debconf tools.
     - A number of questions have to be answered (depending on the package).
@@ -23,7 +33,6 @@ notes:
       installed to see questions/settings available.
     - Some distros will always record tasks involving the setting of passwords as changed. This is due to debconf-get-selections masking passwords.
     - It is highly recommended to add I(no_log=True) to task while handling sensitive information using this module.
-    - Supports C(check_mode).
 requirements:
 - debconf
 - debconf-utils

lib/ansible/modules/debug.py

@@ -38,8 +38,32 @@ options:
     type: int
     default: 0
     version_added: '2.1'
-notes:
+extends_documentation_fragment:
-    - This module is also supported for Windows targets.
+- action_common_attributes
+- action_common_attributes.conn
+- action_common_attributes.flow
+
+attributes:
+    action:
+        support: full
+    async:
+        support: none
+    bypass_host_loop:
+        support: none
+    become:
+        support: none
+    check_mode:
+        support: full
+    diff_mode:
+        support: none
+    connection:
+        support: none
+    delegation:
+        details: Aside from C(register) and/or in combination with C(delegate_facts), it has little effect.
+        support:  partial
+    platform:
+        support: full
+        platforms: all
 seealso:
 - module: ansible.builtin.assert
 - module: ansible.builtin.fail

lib/ansible/modules/dnf.py

@@ -236,6 +236,23 @@ options:
     type: bool
     default: "no"
     version_added: "2.12"
+extends_documentation_fragment:
+- action_common_attributes
+- action_common_attributes.flow
+attributes:
+    action:
+        details: In the case of dnf, it has 2 action plugins that use it under the hood, M(yum) and M(package).
+        support: partial
+    async:
+        support: none
+    bypass_host_loop:
+        support: none
+    check_mode:
+        support: full
+    diff_mode:
+        support: full
+    platform:
+        platforms: rhel
 notes:
   - When used with a `loop:` each package will be processed individually, it is much more efficient to pass the list directly to the `name` option.
   - Group removal doesn't work if the group was installed with Ansible because

lib/ansible/modules/dpkg_selections.py

@@ -29,6 +29,16 @@ options:
         choices: [ 'install', 'hold', 'deinstall', 'purge' ]
         required: true
         type: str
+extends_documentation_fragment:
+- action_common_attributes
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: full
+    platform:
+        support: full
+        platforms: debian
 notes:
     - This module won't cause any packages to be installed/removed/purged, use the C(apt) module for that.
 '''

lib/ansible/modules/expect.py

@@ -57,6 +57,15 @@ options:
 requirements:
   - python >= 2.6
   - pexpect >= 3.3
+extends_documentation_fragment: action_common_attributes
+attributes:
+    check_mode:
+        support: none
+    diff_mode:
+        support: none
+    platform:
+        support: full
+        platforms: posix
 notes:
   - If you want to run a command through the shell (say you are using C(<),
     C(>), C(|), and so on), you must specify a shell in the command such as

lib/ansible/modules/fail.py

@@ -24,8 +24,30 @@ options:
     - If omitted, fail will simply bail out with a generic message.
     type: str
     default: Failed as requested from task
-notes:
+extends_documentation_fragment:
-    - This module is also supported for Windows targets.
+  - action_common_attributes
+  - action_common_attributes.conn
+  - action_common_attributes.flow
+attributes:
+    action:
+        support: full
+    async:
+        support: none
+    become:
+        support: none
+    bypass_host_loop:
+        support: none
+    connection:
+        support: none
+    check_mode:
+        support: none
+    diff_mode:
+        support: none
+    delegation:
+        details: Aside from C(register) and/or in combination with C(delegate_facts), it has little effect.
+        support:  partial
+    platform:
+        platforms: all
 seealso:
 - module: ansible.builtin.assert
 - module: ansible.builtin.debug

lib/ansible/modules/fetch.py

@@ -57,6 +57,27 @@ options:
     - If using multiple hosts with the same filename, the file will be overwritten for each host.
     type: bool
     default: no
+extends_documentation_fragment:
+    - action_common_attributes
+    - action_common_attributes.files
+    - action_common_attributes.flow
+attributes:
+  action:
+    support: full
+  async:
+    support: none
+  bypass_host_loop:
+    support: none
+  check_mode:
+    support: full
+  diff_mode:
+    support: full
+  platform:
+    platforms: posix
+  safe_file_operations:
+    support: none
+  vault:
+    support: none
 notes:
 - When running fetch with C(become), the M(ansible.builtin.slurp) module will also be
   used to fetch the contents of the file for determining the remote

lib/ansible/modules/file.py

@@ -14,7 +14,7 @@ DOCUMENTATION = r'''
 module: file
 version_added: historical
 short_description: Manage files and file properties
-extends_documentation_fragment: files
+extends_documentation_fragment: [files, action_common_attributes]
 description:
 - Set attributes of files, symlinks or directories.
 - Alternatively, remove files, symlinks or directories.
@@ -111,8 +111,14 @@ seealso:
 - module: ansible.builtin.stat
 - module: ansible.builtin.template
 - module: ansible.windows.win_file
-notes:
+attributes:
-- Supports C(check_mode).
+    check_mode:
+        support: full
+    diff_mode:
+        details: permissions and ownership will be shown but file contents on absent/touch will not.
+        support: partial
+    platform:
+        platforms: posix
 author:
 - Ansible Core Team
 - Michael DeHaan

lib/ansible/modules/find.py

@@ -129,6 +129,15 @@ options:
             - Default is unlimited depth.
         type: int
         version_added: "2.6"
+extends_documentation_fragment: action_common_attributes
+attributes:
+    check_mode:
+        details: since this action does not modify the target it just executes normally during check mode
+        support: full
+    diff_mode:
+        support: none
+    platform:
+        platforms: posix
 seealso:
 - module: ansible.windows.win_find
 '''

lib/ansible/modules/gather_facts.py

@@ -12,6 +12,10 @@ DOCUMENTATION = '''
 module: gather_facts
 version_added: 2.8
 short_description: Gathers facts about remote hosts
+extends_documentation_fragment:
+  -  action_common_attributes
+  -  action_common_attributes.facts
+  -  action_common_attributes.flow
 description:
      - This module takes care of executing the R(configured facts modules,FACTS_MODULES), the default is to use the M(ansible.builtin.setup) module.
      - This module is automatically called by playbooks to gather useful variables about remote hosts that can be used in playbooks.
@@ -24,9 +28,27 @@ options:
               This can guarantee the merge order of module facts at the expense of performance.
             - By default it will be true if more than one fact module is used.
         type: bool
+attributes:
+    action:
+        support: full
+    async:
+        details: multiple modules can be executed in parallel or serially, but the action itself will not be async
+        support: partial
+    bypass_host_loop:
+        support: none
+    check_mode:
+        details: since this action should just query the target system info it always runs in check mode
+        support: full
+    diff_mode:
+        support: none
+    facts:
+        support: full
+    platform:
+        details: The action plugin should be able to automatically select the specific platform modules automatically or can be configured manually
+        platforms: all
 notes:
-    - This module is mostly a wrapper around other fact gathering modules.
+    - This is mostly a wrapper around other fact gathering modules.
-    - Options passed to this module must be supported by all the underlying fact modules configured.
+    - Options passed into this action must be supported by all the underlying fact modules configured.
     - Facts returned by each module will be merged, conflicts will favor 'last merged'.
       Order is not guaranteed, when doing parallel gathering on multiple modules.
 author:

lib/ansible/modules/get_url.py

@@ -188,6 +188,14 @@ options:
 # informational: requirements for nodes
 extends_documentation_fragment:
     - files
+    - action_common_attributes
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: none
+    platform:
+        platforms: posix
 notes:
      - For Windows targets, use the M(ansible.windows.win_get_url) module instead.
 seealso:

lib/ansible/modules/getent.py

@@ -44,7 +44,18 @@ options:
             - If a supplied key is missing this will make the task fail if C(yes).
         type: bool
         default: 'yes'
-
+extends_documentation_fragment:
+  - action_common_attributes
+  - action_common_attributes.facts
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: none
+    facts:
+        support: full
+    platform:
+        platforms: posix
 notes:
    - Not all databases support enumeration, check system documentation for details.
 author:

lib/ansible/modules/git.py

@@ -18,6 +18,7 @@ version_added: "0.0.1"
 short_description: Deploy software (or files) from git checkouts
 description:
     - Manage I(git) checkouts of repositories to deploy files or software.
+extends_documentation_fragment: action_common_attributes
 options:
     repo:
         description:
@@ -213,14 +214,19 @@ options:
 
 requirements:
     - git>=1.7.1 (the command line tool)
-
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: full
+    platform:
+        platforms: posix
 notes:
     - "If the task seems to be hanging, first verify remote host is in C(known_hosts).
       SSH will prompt user to authorize the first contact with a remote host.  To avoid this prompt,
       one solution is to use the option accept_hostkey. Another solution is to
       add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling
       the git module, with the following command: ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts."
-    - Supports C(check_mode).
 '''
 
 EXAMPLES = '''

lib/ansible/modules/group.py

@@ -57,13 +57,19 @@ options:
         type: bool
         default: no
         version_added: "2.8"
+extends_documentation_fragment: action_common_attributes
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: none
+    platform:
+        platforms: posix
 seealso:
 - module: ansible.builtin.user
 - module: ansible.windows.win_group
 author:
 - Stephen Fromm (@sfromm)
-notes:
-- Supports C(check_mode).
 '''
 
 EXAMPLES = '''

lib/ansible/modules/group_by.py

@@ -12,6 +12,11 @@ DOCUMENTATION = r'''
 ---
 module: group_by
 short_description: Create Ansible groups based on facts
+extends_documentation_fragment:
+  - action_common_attributes
+  - action_common_attributes.conn
+  - action_common_attributes.flow
+  - action_core
 description:
 - Use facts to create ad-hoc groups that can be used later in a playbook.
 - This module is also supported for Windows targets.
@@ -28,9 +33,31 @@ options:
     type: list
     default: all
     version_added: "2.4"
+attributes:
+    action:
+      support: full
+    become:
+      support: none
+    bypass_host_loop:
+      support: full
+    bypass_task_loop:
+      support: none
+    check_mode:
+      details: While this makes no changes to target systems the 'in memory' inventory will still be altered
+      support: partial
+    core:
+      details: While parts of this action are implemented in core, other parts are still available as normal plugins and can be partially overridden
+      support: partial
+    connection:
+        support: none
+    delegation:
+        support: none
+    diff_mode:
+      support: none
+    platform:
+        platforms: all
 notes:
 - Spaces in group names are converted to dashes '-'.
-- This module is also supported for Windows targets.
 - Though this module does not change the remote host,
   we do provide 'changed' status as it can be useful
   for those trying to track inventory changes.

lib/ansible/modules/hostname.py

@@ -25,7 +25,6 @@ notes:
       or M(ansible.builtin.replace).
     - On macOS, this module uses C(scutil) to set C(HostName), C(ComputerName), and C(LocalHostName). Since C(LocalHostName)
       cannot contain spaces or most special characters, this module will replace characters when setting C(LocalHostName).
-    - Supports C(check_mode).
 options:
     name:
         description:
@@ -42,6 +41,18 @@ options:
         choices: ['alpine', 'debian', 'freebsd', 'generic', 'macos', 'macosx', 'darwin', 'openbsd', 'openrc', 'redhat', 'sles', 'solaris', 'systemd']
         type: str
         version_added: '2.9'
+extends_documentation_fragment:
+- action_common_attributes
+- action_common_attributes.facts
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: full
+    facts:
+        support: full
+    platform:
+        platforms: posix
 '''
 
 EXAMPLES = '''

lib/ansible/modules/import_playbook.py

@@ -23,26 +23,18 @@ options:
     description:
       - The name of the imported playbook is specified directly without any other option.
 extends_documentation_fragment:
-- action_common_attributes
+  - action_common_attributes
+  - action_common_attributes.conn
+  - action_common_attributes.flow
+  - action_core
+  - action_core.import
 attributes:
-    async:
+    check_mode:
-        support: none
-    become:
-        support: none
-    bypass_host_loop:
         support: full
-    conditional:
+    diff_mode:
-        support: none
-    connection:
-        support: none
-    delegation:
-        support: none
-    loops:
-        support: none
-    tags:
-        support: none
-    until:
         support: none
+    platform:
+        platforms: all
 notes:
   - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
 seealso:

lib/ansible/modules/import_role.py

@@ -58,25 +58,15 @@ options:
     default: yes
     version_added: '2.11'
 extends_documentation_fragment:
-- action_common_attributes
+    - action_common_attributes
+    - action_common_attributes.conn
+    - action_common_attributes.flow
+    - action_core
+    - action_core.import
 attributes:
-    async:
+    check_mode:
-        support: none
+      support: full
-    become:
+    diff_mode:
-        support: none
-    bypass_host_loop:
-        support: partial
-    conditional:
-        support: none
-    connection:
-        support: none
-    delegation:
-        support: none
-    loops:
-        support: none
-    tags:
-        support: none
-    until:
       support: none
 notes:
   - Handlers are made available to the whole play.

lib/ansible/modules/import_tasks.py

@@ -23,28 +23,18 @@ options:
       - Most keywords, including loops and conditionals, only applied to the imported tasks, not to this statement itself.
       - If you need any of those to apply, use M(ansible.builtin.include_tasks) instead.
 extends_documentation_fragment:
-- action_common_attributes
+    - action_common_attributes
+    - action_common_attributes.conn
+    - action_common_attributes.flow
+    - action_core
+    - action_core.import
 attributes:
-    async:
+    check_mode:
       support: none
-    become:
+    diff_mode:
-        support: none
-    bypass_host_loop:
-        support: partial
-    conditional:
-        support: none
-    connection:
-        support: none
-    delegation:
-        support: none
-    loops:
-        support: none
-    tags:
-        support: none
-    until:
       support: none
 notes:
-  - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
+  - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module
 seealso:
 - module: ansible.builtin.import_playbook
 - module: ansible.builtin.import_role

lib/ansible/modules/include_role.py

@@ -73,11 +73,19 @@ options:
     type: bool
     default: yes
     version_added: '2.11'
+extends_documentation_fragment:
+    - action_common_attributes
+    - action_common_attributes.conn
+    - action_common_attributes.flow
+    - action_core
+    - action_core.include
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: none
 notes:
-  - Handlers are made available to the whole play.
+  - Handlers and are made available to the whole play.
-  - Before Ansible 2.4, as with C(include), this task could be static or dynamic, If static, it implied that it won't
-    need templating, loops or conditionals and will show included tasks in the C(--list) options. Ansible would try to
-    autodetect what is needed, but you can set C(static) to C(yes) or C(no) at task level to control this.
   - After Ansible 2.4, you can use M(ansible.builtin.import_role) for C(static) behaviour and this action for C(dynamic) one.
 seealso:
 - module: ansible.builtin.import_playbook

lib/ansible/modules/include_tasks.py

@@ -34,8 +34,17 @@ options:
       - |
         Supplying a file name via free-form C(- include_tasks: file.yml) of a file to be included is the equivalent
         of specifying an argument of I(file).
-notes:
+extends_documentation_fragment:
-  - This is a core feature of the Ansible, rather than a module, and cannot be overridden like a module.
+    - action_common_attributes
+    - action_common_attributes.conn
+    - action_common_attributes.flow
+    - action_core
+    - action_core.include
+attributes:
+    check_mode:
+        support: none
+    diff_mode:
+        support: none
 seealso:
 - module: ansible.builtin.import_playbook
 - module: ansible.builtin.import_role

lib/ansible/modules/include_vars.py

@@ -82,8 +82,31 @@ options:
     description:
       - This module allows you to specify the 'file' option directly without any other options.
       - There is no 'free-form' option, this is just an indicator, see example below.
-notes:
+extends_documentation_fragment:
-  - This module is also supported for Windows targets.
+    - action_common_attributes
+    - action_common_attributes.conn
+    - action_common_attributes.flow
+    - action_core
+attributes:
+    action:
+        details: While the action plugin does do some of the work it relies on the core engine to actually create the variables, that part cannot be overriden
+        support: partial
+    bypass_host_loop:
+        support: none
+    bypass_task_loop:
+        support: none
+    check_mode:
+        support: full
+    delegation:
+        details:
+            - while variable assignment can be delegated to a different host the execution context is always the current invenotory_hostname
+            - connection variables, if set at all, would reflect the host it would target, even if we are not connecting at all in this case
+        support: partial
+    diff_mode:
+        support: none
+    core:
+        details: While parts of this action are implemented in core, other parts are still available as normal plugins and can be partially overridden
+        support: partial
 seealso:
 - module: ansible.builtin.set_fact
 - ref: playbooks_delegation

lib/ansible/modules/iptables.py

@@ -24,6 +24,14 @@ description:
     only manipulates the current rules that are present in memory. This is the
     same as the behaviour of the C(iptables) and C(ip6tables) command which
     this module uses internally.
+extends_documentation_fragment: action_common_attributes
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: none
+    platform:
+        platforms: linux
 notes:
   - This module just deals with individual rules.If you need advanced
     chaining of rules the recommended way is to template the iptables restore

lib/ansible/modules/meta.py

@@ -37,13 +37,37 @@ options:
           Note that with C(serial=0) or undefined this behaves the same as C(end_play).
     choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection, end_batch ]
     required: true
+extends_documentation_fragment:
+    - action_common_attributes
+    - action_common_attributes.conn
+    - action_common_attributes.flow
+    - action_core
+attributes:
+    action:
+      support: none
+    bypass_host_loop:
+      details: Some of the subactions ignore the host loop, see the description above for each specific action for the exceptions
+      support: partial
+    bypass_task_loop:
+      details: Most of the subactions ignore the task loop, see the description above for each specific action for the exceptions
+      support: partial
+    check_mode:
+      details: While these actions don't modify the targets directly they do change possible states of the target within the run
+      support: partial
+    delegation:
+      support: none
+    diff_mode:
+      support: none
+    ignore_conditional:
+      details: Only some options support conditionals and when they do they act 'bypassing the host loop', taking the values from first available host
+      support: partial
+    connection:
+      details: Most options in this action do not use a connection, except C(reset_connection) which still does not connect to the remote
+      support: partial
 notes:
-    - C(meta) is not really a module nor action_plugin as such it cannot be overwritten.
     - C(clear_facts) will remove the persistent facts from M(ansible.builtin.set_fact) using C(cacheable=True),
       but not the current host variable it creates for the current run.
-    - Looping on meta tasks is not supported.
     - Skipping C(meta) tasks with tags is not supported before Ansible 2.11.
-    - This module is also supported for Windows targets.
 seealso:
 - module: ansible.builtin.assert
 - module: ansible.builtin.fail

lib/ansible/modules/yum.py

@@ -242,6 +242,23 @@ options:
     default: "no"
     type: bool
     version_added: "2.12"
+extends_documentation_fragment:
+- action_common_attributes
+- action_common_attributes.flow
+attributes:
+    action:
+        details: In the case of yum, it has 2 action plugins that use it under the hood, M(yum) and M(package).
+        support: partial
+    async:
+        support: none
+    bypass_host_loop:
+        support: none
+    check_mode:
+        support: full
+    diff_mode:
+        support: full
+    platform:
+        platforms: rhel
 notes:
   - When used with a `loop:` each package will be processed individually,
     it is much more efficient to pass the list directly to the `name` option.

lib/ansible/modules/yum_repository.py

@@ -356,8 +356,15 @@ options:
     type: str
 
 extends_documentation_fragment:
+    - action_common_attributes
     - files
-
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: full
+    platform:
+        platforms: rhel
 notes:
   - All comments will be removed if modifying an existing repo file.
   - Section order is preserved in an existing repo file.

lib/ansible/plugins/doc_fragments/action_common_attributes.py

@@ -1,6 +1,5 @@
 # -*- coding: utf-8 -*-
-
+# Copyright: Ansible Project
-# Copyright: (c) 2015, Ansible, Inc
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
@@ -11,84 +10,62 @@ class ModuleDocFragment(object):
     # Standard documentation fragment
     DOCUMENTATION = r'''
 attributes:
-    action:
+    check_mode:
-      description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller
+      description: Can run in check_mode and return changed status prediction withought modifying target
-      support: none
+    diff_mode:
+      description: Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
+    platform:
+      description: Target OS/families that can be operated against
+      support: full
+'''
+
+    ACTIONGROUPS = r'''
+attributes:
     action_group:
       description: Action is part of action_group(s), for convenient setting of module_defaults.
       support: none
       membership: []
-    api:
+'''
-      description: Instead of executing code on a target, this action interacts with an API on behalf of the target.
+
-      support: none
+    CONN = r'''
-    async:
+attributes:
-      description: Supports being used with the ``async`` keyword
-      support: full
     become:
       description: Is usable alongside become keywords
-      support: full
-    bypass_host_loop:
-      description: Forces a 'global' task that does not execute per host, this bypasses per host templating and serial,
-                   throttle and other loop considerations.  Also, this action cannot be used in non lockstep strategies
-      support: none
-    check_mode:
-      description: Can run in check_mode and return changed status prediction withought modifying target
-      support: none
     connection:
       description: Uses the target's configured connection information to execute code on it
-      support: full
-    conditional:
-      description: Will respect the `when` keyword  per item loop or task (when no loop is present)
-      support: full
     delegation:
       description: Can be used in conjunction with delegate_to and related keywords
-      support: full
+'''
-    diff_mode:
+
-      description: Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
+    FACTS = r'''
-      support: none
+attributes:
     facts:
-      description: Action returns an ``ansible_facts`` dictionary that will update existing host facts
+      description: Action returns an C(ansible_facts) dictionary that will update existing host facts
-      support: none
+'''
-    forced_local:
+
-      description: The connection itself is passed to the action while the code is still executed on the controller
+    FILES = r'''
-      support: none
+attributes:
-    forced_action_plugin:
-      description: This action uses a specific action plugin instead of 'normal' or matching by name
-      support: none
-      action_plugin: none
-    info:
-      description: This returns general info (not facts) that you might want to register into a variable for later use
-      support: none
-    loops:
-      description: both ``loop`` and ``with_`` looping keywords will be honored
-      support: full
-    proprietary:
-      description: Designed to only be run against specific proprietary OS(s), normally a network appliance or similar
-      support: none
-      platforms: []
-    posix:
-      description: Can be run against most POSIX (and GNU/Linux) OS targets
-      support: full
     safe_file_operations:
       description: Uses Ansbile's strict file operation functions to ensure proper permissions and avoid data corruption
-      support: none
-    tags:
-      description: Tags will be evaluated to determine if this task considered for execution
-      support: full
-    tty:
-      description: requires direct access to a TTY
-      support: none
-    turbo:
-      description: Uses an Ansible supplied caching mechanism (Turbo!) on the remote for authentication and
-                   3rd party libraries to speed up recurrent execution
-      support: none
-    until:
-      description: Usable with until/retry loops
-      support: full
     vault:
       description: Can automatically decrypt Ansible vaulted files
-      support: none
+'''
-    windows:
+
-      description: Can be run against Windows OS targets
+    FLOW = r'''
-      support: none
+attributes:
+    action:
+      description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller
+    async:
+      description: Supports being used with the C(async) keyword
+    bypass_host_loop:
+      description:
+            - Forces a 'global' task that does not execute per host, this bypasses per host templating and serial,
+              throttle and other loop considerations
+            - Conditionals will work as if C(run_once) is being used, variables used will be from the first available host
+            - This action will not work normally outside of lockstep strategies
+'''
+    RAW = r'''
+attributes:
+    raw:
+      description: Indicates if an action takes a 'raw' or 'free form' string as an option and has it's own special parsing of it
 '''

lib/ansible/plugins/doc_fragments/action_core.py

@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+# Copyright: (c) , Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+# WARNING: this is mostly here as a convinence for documenting core behaviours, no plugin outside of ansbile-core should use this file
+class ModuleDocFragment(object):
+
+    # requires action_common
+    DOCUMENTATION = r'''
+attributes:
+    async:
+      support: none
+    become:
+      support: none
+    bypass_task_loop:
+      description: These tasks ignore the C(loop) and C(with_) keywords
+    core:
+      description: This is a 'core engine' feature and is not implemented like most task actions, so it is not overridable in any way via the plugin system.
+      support: full
+    connection:
+      support: none
+    ignore_conditional:
+      support: none
+      description: The action is not subject to conditional execution so it will ignore the C(when:) keyword
+    platform:
+      support: full
+      platforms: all
+    until:
+      description: Denotes if this action objeys until/retry/poll keywords
+      support: full
+    tags:
+      description: Allows for the 'tags' keyword to control the selection of this action for execution
+      support: full
+'''
+
+    # also requries core above
+    IMPORT = r'''
+attributes:
+    action:
+      details: While this action executes locally on the controller it is not governed by an action plugin
+      support: none
+    bypass_host_loop:
+      details: While the import can be host specific and runs per host it is not dealing with all available host variables,
+               use an include instead for those cases
+      support: partial
+    bypass_task_loop:
+      details: The task itself is not looped, but the loop is applied to each imported task
+      support: partial
+    delegation:
+      details: Since there are no connection nor facts, there is no sense in delegating imports
+      support: none
+    ignore_conditional:
+      details: While the action itself will ignore the conditional, it will be inherited by the imported tasks themselves
+      support: partial
+    tags:
+      details: Tags are not interpreted for this action, they are applied to the imported tasks
+      support: none
+    until:
+      support: none
+'''
+    # also requires core above
+    INCLUDE = r'''
+attributes:
+    action:
+      details: While this action executes locally on the controller it is not governed by an action plugin
+      support: none
+    bypass_host_loop:
+      support: none
+    bypass_task_loop:
+      support: none
+    delegation:
+      details: Since there are no connection nor facts, there is no sense in delegating includes
+      support: none
+    tags:
+      details: Tags are interpreted by this action but are not automatically inherited by the include tasks, see C(apply)
+      support: partial
+'''

test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py

@@ -527,7 +527,8 @@ def doc_schema(module_name, for_collection=False, deprecated_module=False):
 
     def add_default_attributes(more=None):
         schema = {
-            'description': any_string_types,
+            'description': Any(list_string_types, *string_types),
+            'details': Any(list_string_types, *string_types),
             'support': any_string_types,
             'version_added_collection': any_string_types,
             'version_added': any_string_types,
@@ -540,8 +541,9 @@ def doc_schema(module_name, for_collection=False, deprecated_module=False):
         All(
             Schema({
                 any_string_types: {
-                    Required('description'): any_string_types,
+                    Required('description'): Any(list_string_types, *string_types),
                     Required('support'): Any('full', 'partial', 'none'),
+                    'details': Any(list_string_types, *string_types),
                     'version_added_collection': collection_name,
                     'version_added': version(for_collection=for_collection),
                 },
@@ -555,8 +557,8 @@ def doc_schema(module_name, for_collection=False, deprecated_module=False):
                 'forced_action_plugin': add_default_attributes({
                     Required('action_plugin'): any_string_types,
                 }),
-                'proprietary': add_default_attributes({
+                'platform': add_default_attributes({
-                    Required('platforms'): list_string_types,
+                    Required('platforms'): Any(list_string_types, *string_types)
                 }),
             }, extra=PREVENT_EXTRA),
         )