[PR #6671/6fc1df9b backport][stable-7] Use semantic markup (modules a-c) (#6701)

Use semantic markup (modules a-c) (#6671)

* Use semantic markup.

* E() now works better.

(cherry picked from commit 6fc1df9b83)

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

plugins/lookup/dependent.py

@@ -22,7 +22,7 @@ options:
         The name is the index that is used in the result object. The value is iterated over as described below.
       - If the value is a list, it is simply iterated over.
       - If the value is a dictionary, it is iterated over and returned as if they would be processed by the
-        R(ansible.builtin.dict2items filter,ansible_collections.ansible.builtin.dict2items_filter).
+        P(ansible.builtin.dict2items#filter) filter.
       - If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen
         elements with C(item.<index_name>). The result must be a list or a dictionary.
     type: list

plugins/lookup/flattened.py

@@ -19,7 +19,7 @@ DOCUMENTATION = '''
         elements: raw
         required: true
     notes:
-      - Unlike the R(items lookup,ansible_collections.ansible.builtin.items_lookup) which only flattens 1 level,
+      - Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level,
         this plugin will continue to flatten until it cannot find lists anymore.
       - Aka highlander plugin, there can only be one (list).
 '''

plugins/modules/alerta_customer.py

@@ -58,7 +58,7 @@ options:
   state:
     description:
       - Whether the customer should exist or not.
-      - Both I(customer) and I(match) identify a customer that should be added or removed.
+      - Both O(customer) and O(match) identify a customer that should be added or removed.
     type: str
     choices: [ absent, present ]
     default: present

plugins/modules/ali_instance.py

@@ -51,12 +51,12 @@ options:
       type: str
     image_id:
       description:
-        - Image ID used to launch instances. Required when I(state=present) and creating new ECS instances.
+        - Image ID used to launch instances. Required when O(state=present) and creating new ECS instances.
       aliases: ['image']
       type: str
     instance_type:
       description:
-        - Instance type used to launch instances. Required when I(state=present) and creating new ECS instances.
+        - Instance type used to launch instances. Required when O(state=present) and creating new ECS instances.
       aliases: ['type']
       type: str
     security_groups:
@@ -95,7 +95,7 @@ options:
     max_bandwidth_out:
       description:
         - Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second).
-          Required when I(allocate_public_ip=true). Ignored when I(allocate_public_ip=false).
+          Required when O(allocate_public_ip=true). Ignored when O(allocate_public_ip=false).
       default: 0
       type: int
     host_name:
@@ -134,16 +134,16 @@ options:
       type: str
     count:
       description:
-        - The number of the new instance. An integer value which indicates how many instances that match I(count_tag)
+        - The number of the new instance. An integer value which indicates how many instances that match O(count_tag)
           should be running. Instances are either created or terminated based on this value.
       default: 1
       type: int
     count_tag:
       description:
-      - I(count) determines how many instances based on a specific tag criteria should be present.
+      - O(count) determines how many instances based on a specific tag criteria should be present.
         This can be expressed in multiple ways and is shown in the EXAMPLES section.
-        The specified count_tag must already exist or be passed in as the I(tags) option.
+        The specified count_tag must already exist or be passed in as the O(tags) option.
-        If it is not specified, it will be replaced by I(instance_name).
+        If it is not specified, it will be replaced by O(instance_name).
       type: str
     allocate_public_ip:
       description:
@@ -159,7 +159,7 @@ options:
       type: str
     period:
       description:
-        - The charge duration of the instance, in months. Required when I(instance_charge_type=PrePaid).
+        - The charge duration of the instance, in months. Required when O(instance_charge_type=PrePaid).
         - The valid value are [1-9, 12, 24, 36].
       default: 1
       type: int
@@ -170,13 +170,13 @@ options:
       default: false
     auto_renew_period:
       description:
-        - The duration of the automatic renew the charge of the instance. Required when I(auto_renew=true).
+        - The duration of the automatic renew the charge of the instance. Required when O(auto_renew=true).
       choices: [1, 2, 3, 6, 12]
       type: int
     instance_ids:
       description:
         - A list of instance ids. It is required when need to operate existing instances.
-          If it is specified, I(count) will lose efficacy.
+          If it is specified, O(count) will lose efficacy.
       type: list
       elements: str
     force:
@@ -186,7 +186,7 @@ options:
       type: bool
     tags:
       description:
-        - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. C({"key":"value"})
+        - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. V({"key":"value"})
       aliases: ["instance_tags"]
       type: dict
       version_added: '0.2.0'
@@ -229,7 +229,7 @@ options:
       version_added: '0.2.0'
     period_unit:
       description:
-        - The duration unit that you will buy the resource. It is valid when I(instance_charge_type=PrePaid).
+        - The duration unit that you will buy the resource. It is valid when O(instance_charge_type=PrePaid).
       choices: ['Month', 'Week']
       default: 'Month'
       type: str
@@ -237,10 +237,10 @@ options:
     dry_run:
       description:
         - Specifies whether to send a dry-run request.
-        - If I(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the
+        - If O(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the
           required parameters are set, and validates the request format, service permissions, and available ECS instances.
           If the validation fails, the corresponding error code is returned. If the validation succeeds, the DryRunOperation error code is returned.
-        - If I(dry_run=false), A request is sent. If the validation succeeds, the instance is created.
+        - If O(dry_run=false), A request is sent. If the validation succeeds, the instance is created.
       default: false
       type: bool
       version_added: '0.2.0'

plugins/modules/ali_instance_info.py

@@ -53,9 +53,9 @@ options:
       description:
         - A dict of filters to apply. Each dict item consists of a filter key and a filter value. The filter keys can be
           all of request parameters. See U(https://www.alibabacloud.com/help/doc-detail/25506.htm) for parameter details.
-          Filter keys can be same as request parameter name or be lower case and use underscore ("_") or dash ("-") to
+          Filter keys can be same as request parameter name or be lower case and use underscore (V("_")) or dash (V("-")) to
-          connect different words in one parameter. 'InstanceIds' should be a list.
+          connect different words in one parameter. C(InstanceIds) should be a list.
-          'Tag.n.Key' and 'Tag.n.Value' should be a dict and using I(tags) instead.
+          C(Tag.n.Key) and C(Tag.n.Value) should be a dict and using O(tags) instead.
       type: dict
       version_added: '0.2.0'
 author:

plugins/modules/alternatives.py

@@ -44,21 +44,21 @@ options:
     description:
       - The path to the symbolic link that should point to the real executable.
       - This option is always required on RHEL-based distributions. On Debian-based distributions this option is
-        required when the alternative I(name) is unknown to the system.
+        required when the alternative O(name) is unknown to the system.
     type: path
   priority:
     description:
-      - The priority of the alternative. If no priority is given for creation C(50) is used as a fallback.
+      - The priority of the alternative. If no priority is given for creation V(50) is used as a fallback.
     type: int
   state:
     description:
-      - C(present) - install the alternative (if not already installed), but do
+      - V(present) - install the alternative (if not already installed), but do
         not set it as the currently selected alternative for the group.
-      - C(selected) - install the alternative (if not already installed), and
+      - V(selected) - install the alternative (if not already installed), and
         set it as the currently selected alternative for the group.
-      - C(auto) - install the alternative (if not already installed), and
+      - V(auto) - install the alternative (if not already installed), and
         set the group to auto mode. Added in community.general 5.1.0.
-      - C(absent) - removes the alternative. Added in community.general 5.1.0.
+      - V(absent) - removes the alternative. Added in community.general 5.1.0.
     choices: [ present, selected, auto, absent ]
     default: selected
     type: str

plugins/modules/ansible_galaxy_install.py

@@ -37,9 +37,9 @@ options:
   type:
     description:
       - The type of installation performed by C(ansible-galaxy).
-      - If I(type) is C(both), then I(requirements_file) must be passed and it may contain both roles and collections.
+      - If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections.
-      - "Note however that the opposite is not true: if using a I(requirements_file), then I(type) can be any of the three choices."
+      - "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices."
-      - "B(Ansible 2.9): The option C(both) will have the same effect as C(role)."
+      - "B(Ansible 2.9): The option V(both) will have the same effect as V(role)."
     type: str
     choices: [collection, role, both]
     required: true
@@ -48,22 +48,22 @@ options:
       - Name of the collection or role being installed.
       - >
         Versions can be specified with C(ansible-galaxy) usual formats.
-        For example, the collection C(community.docker:1.6.1) or the role C(ansistrano.deploy,3.8.0).
+        For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0).
-      - I(name) and I(requirements_file) are mutually exclusive.
+      - O(name) and O(requirements_file) are mutually exclusive.
     type: str
   requirements_file:
     description:
       - Path to a file containing a list of requirements to be installed.
-      - It works for I(type) equals to C(collection) and C(role).
+      - It works for O(type) equals to V(collection) and V(role).
-      - I(name) and I(requirements_file) are mutually exclusive.
+      - O(name) and O(requirements_file) are mutually exclusive.
-      - "B(Ansible 2.9): It can only be used to install either I(type=role) or I(type=collection), but not both at the same run."
+      - "B(Ansible 2.9): It can only be used to install either O(type=role) or O(type=collection), but not both at the same run."
     type: path
   dest:
     description:
-      - The path to the directory containing your collections or roles, according to the value of I(type).
+      - The path to the directory containing your collections or roles, according to the value of O(type).
       - >
-        Please notice that C(ansible-galaxy) will not install collections with I(type=both), when I(requirements_file)
+        Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file)
-        contains both roles and collections and I(dest) is specified.
+        contains both roles and collections and O(dest) is specified.
     type: path
   no_deps:
     description:
@@ -74,8 +74,8 @@ options:
   force:
     description:
       - Force overwriting an existing role or collection.
-      - Using I(force=true) is mandatory when downgrading.
+      - Using O(force=true) is mandatory when downgrading.
-      - "B(Ansible 2.9 and 2.10): Must be C(true) to upgrade roles and collections."
+      - "B(Ansible 2.9 and 2.10): Must be V(true) to upgrade roles and collections."
     type: bool
     default: false
   ack_ansible29:
@@ -92,7 +92,7 @@ options:
       - Support for those versions will be removed in community.general 8.0.0.
         At the same time, this option will be removed without any deprecation warning!
       - This option is completely ignored if using a version of ansible-core/ansible-base/Ansible greater than C(2.11).
-      - For the sake of conciseness, setting this parameter to C(true) implies I(ack_ansible29=true).
+      - For the sake of conciseness, setting this parameter to V(true) implies O(ack_ansible29=true).
     type: bool
     default: false
 """
@@ -124,29 +124,29 @@ EXAMPLES = """
 
 RETURN = """
   type:
-    description: The value of the I(type) parameter.
+    description: The value of the O(type) parameter.
     type: str
     returned: always
   name:
-    description: The value of the I(name) parameter.
+    description: The value of the O(name) parameter.
     type: str
     returned: always
   dest:
-    description: The value of the I(dest) parameter.
+    description: The value of the O(dest) parameter.
     type: str
     returned: always
   requirements_file:
-    description: The value of the I(requirements_file) parameter.
+    description: The value of the O(requirements_file) parameter.
     type: str
     returned: always
   force:
-    description: The value of the I(force) parameter.
+    description: The value of the O(force) parameter.
     type: bool
     returned: always
   installed_roles:
     description:
-      - If I(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
+      - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
-      - If I(name) is specified, returns that role name and the version installed per path.
+      - If O(name) is specified, returns that role name and the version installed per path.
       - "B(Ansible 2.9): Returns empty because C(ansible-galaxy) has no C(list) subcommand."
     type: dict
     returned: always when installing roles
@@ -162,8 +162,8 @@ RETURN = """
         ansistrano.deploy: 3.8.0
   installed_collections:
     description:
-      - If I(requirements_file) is specified instead, returns dictionary with all the collections installed per path.
+      - If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path.
-      - If I(name) is specified, returns that collection name and the version installed per path.
+      - If O(name) is specified, returns that collection name and the version installed per path.
       - "B(Ansible 2.9): Returns empty because C(ansible-galaxy) has no C(list) subcommand."
     type: dict
     returned: always when installing collections

plugins/modules/apache2_module.py

@@ -37,7 +37,7 @@ options:
      description:
          - Identifier of the module as listed by C(apache2ctl -M).
            This is optional and usually determined automatically by the common convention of
-           appending C(_module) to I(name) as well as custom exception for popular modules.
+           appending V(_module) to O(name) as well as custom exception for popular modules.
      required: false
    force:
      description:

plugins/modules/apk.py

@@ -17,7 +17,7 @@ DOCUMENTATION = '''
 module: apk
 short_description: Manages apk packages
 description:
-  - Manages I(apk) packages for Alpine Linux.
+  - Manages C(apk) packages for Alpine Linux.
 author: "Kevin Brebanov (@kbrebanov)"
 extends_documentation_fragment:
   - community.general.attributes
@@ -35,7 +35,7 @@ options:
     default: false
   name:
     description:
-      - A package name, like C(foo), or multiple packages, like C(foo, bar).
+      - A package name, like V(foo), or multiple packages, like V(foo, bar).
     type: list
     elements: str
   no_cache:
@@ -53,9 +53,9 @@ options:
   state:
     description:
       - Indicates the desired package(s) state.
-      - C(present) ensures the package(s) is/are present. C(installed) can be used as an alias.
+      - V(present) ensures the package(s) is/are present. V(installed) can be used as an alias.
-      - C(absent) ensures the package(s) is/are absent. C(removed) can be used as an alias.
+      - V(absent) ensures the package(s) is/are absent. V(removed) can be used as an alias.
-      - C(latest) ensures the package(s) is/are present and the latest version(s).
+      - V(latest) ensures the package(s) is/are present and the latest version(s).
     default: present
     choices: [ "present", "absent", "latest", "installed", "removed" ]
     type: str
@@ -76,8 +76,8 @@ options:
     default: /etc/apk/world
     version_added: 5.4.0
 notes:
-  - 'I(name) and I(upgrade) are mutually exclusive.'
+  - 'O(name) and O(upgrade) are mutually exclusive.'
-  - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the I(name) option.
+  - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option.
 '''
 
 EXAMPLES = '''

plugins/modules/apt_repo.py

@@ -41,7 +41,7 @@ options:
   remove_others:
     description:
       - Remove other then added repositories
-      - Used if I(state=present)
+      - Used if O(state=present)
     type: bool
     default: false
   update:

plugins/modules/apt_rpm.py

@@ -16,7 +16,7 @@ DOCUMENTATION = '''
 module: apt_rpm
 short_description: APT-RPM package manager
 description:
-  - Manages packages with I(apt-rpm). Both low-level (I(rpm)) and high-level (I(apt-get)) package manager binaries required.
+  - Manages packages with C(apt-rpm). Both low-level (C(rpm)) and high-level (C(apt-get)) package manager binaries required.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:

plugins/modules/archive.py

@@ -20,7 +20,7 @@ extends_documentation_fragment:
 description:
     - Creates or extends an archive.
     - The source and archive are on the remote host, and the archive I(is not) copied to the local host.
-    - Source files can be deleted after archival by specifying I(remove=True).
+    - Source files can be deleted after archival by specifying O(remove=True).
 attributes:
   check_mode:
     support: full
@@ -43,20 +43,20 @@ options:
   dest:
     description:
       - The file name of the destination archive. The parent directory must exists on the remote host.
-      - This is required when C(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list.
+      - This is required when O(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list.
       - If the destination archive already exists, it will be truncated and overwritten.
     type: path
   exclude_path:
     description:
-      - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from I(path) list and glob expansion.
+      - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from O(path) list and glob expansion.
-      - Use I(exclusion_patterns) to instead exclude files or subdirectories below any of the paths from the I(path) list.
+      - Use O(exclusion_patterns) to instead exclude files or subdirectories below any of the paths from the O(path) list.
     type: list
     elements: path
     default: []
   exclusion_patterns:
     description:
       - Glob style patterns to exclude files or directories from the resulting archive.
-      - This differs from I(exclude_path) which applies only to the source paths from I(path).
+      - This differs from O(exclude_path) which applies only to the source paths from O(path).
     type: list
     elements: path
     version_added: 3.2.0
@@ -73,7 +73,7 @@ options:
     type: bool
     default: false
 notes:
-    - Can produce I(gzip), I(bzip2), I(lzma), and I(zip) compressed files or archives.
+    - Can produce C(gzip), C(bzip2), C(lzma), and C(zip) compressed files or archives.
     - This module uses C(tarfile), C(zipfile), C(gzip), and C(bz2) packages on the target host to create archives.
       These are part of the Python standard library for Python 2 and 3.
 requirements:
@@ -149,11 +149,11 @@ state:
     returned: always
 dest_state:
     description:
-      - The state of the I(dest) file.
+      - The state of the O(dest) file.
       - C(absent) when the file does not exist.
       - C(archive) when the file is an archive.
       - C(compress) when the file is compressed, but not an archive.
-      - C(incomplete) when the file is an archive, but some files under I(path) were not found.
+      - C(incomplete) when the file is an archive, but some files under O(path) were not found.
     type: str
     returned: success
     version_added: 3.4.0

plugins/modules/awall.py

@@ -16,7 +16,7 @@ short_description: Manage awall policies
 author: Ted Trask (@tdtrask) <ttrask01@yahoo.com>
 description:
   - This modules allows for enable/disable/activate of C(awall) policies.
-  - Alpine Wall (I(awall)) generates a firewall configuration from the enabled policy files
+  - Alpine Wall (C(awall)) generates a firewall configuration from the enabled policy files
     and activates the configuration on the system.
 extends_documentation_fragment:
   - community.general.attributes
@@ -41,11 +41,11 @@ options:
     description:
       - Activate the new firewall rules.
       - Can be run with other steps or on its own.
-      - Idempotency is affected if I(activate=true), as the module will always report a changed state.
+      - Idempotency is affected if O(activate=true), as the module will always report a changed state.
     type: bool
     default: false
 notes:
-    - At least one of I(name) and I(activate) is required.
+    - At least one of O(name) and O(activate) is required.
 '''
 
 EXAMPLES = r'''

plugins/modules/bearychat.py

@@ -27,7 +27,7 @@ options:
     description:
       - BearyChat WebHook URL. This authenticates you to the bearychat
         service. It looks like
-        C(https://hook.bearychat.com/=ae2CF/incoming/e61bd5c57b164e04b11ac02e66f47f60).
+        V(https://hook.bearychat.com/=ae2CF/incoming/e61bd5c57b164e04b11ac02e66f47f60).
     required: true
   text:
     type: str
@@ -35,14 +35,14 @@ options:
       - Message to send.
   markdown:
     description:
-      - If C(true), text will be parsed as markdown.
+      - If V(true), text will be parsed as markdown.
     default: true
     type: bool
   channel:
     type: str
     description:
       - Channel to send the message to. If absent, the message goes to the
-        default channel selected by the I(url).
+        default channel selected by the O(url).
   attachments:
     type: list
     elements: dict

plugins/modules/bitbucket_access_key.py

@@ -33,7 +33,7 @@ options:
   workspace:
     description:
       - The repository owner.
-      - I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user).
+      - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
     type: str
     required: true
   key:

plugins/modules/bitbucket_pipeline_key_pair.py

@@ -33,7 +33,7 @@ options:
   workspace:
     description:
       - The repository owner.
-      - I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user).
+      - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
     type: str
     required: true
   public_key:

plugins/modules/bitbucket_pipeline_known_host.py

@@ -14,7 +14,7 @@ module: bitbucket_pipeline_known_host
 short_description: Manages Bitbucket pipeline known hosts
 description:
   - Manages Bitbucket pipeline known hosts under the "SSH Keys" menu.
-  - The host fingerprint will be retrieved automatically, but in case of an error, one can use I(key) field to specify it manually.
+  - The host fingerprint will be retrieved automatically, but in case of an error, one can use O(key) field to specify it manually.
 author:
   - Evgeniy Krysanov (@catcombo)
 extends_documentation_fragment:
@@ -36,7 +36,7 @@ options:
   workspace:
     description:
       - The repository owner.
-      - I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user).
+      - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
     type: str
     required: true
   name:

plugins/modules/bitbucket_pipeline_variable.py

@@ -33,7 +33,7 @@ options:
   workspace:
     description:
       - The repository owner.
-      - I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user).
+      - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
     type: str
     required: true
   name:
@@ -58,7 +58,7 @@ options:
     choices: [ absent, present ]
 notes:
   - Check mode is supported.
-  - For secured values return parameter C(changed) is always C(True).
+  - For secured values return parameter C(changed) is always V(true).
 '''
 
 EXAMPLES = r'''

plugins/modules/btrfs_subvolume.py

@@ -23,7 +23,7 @@ options:
         default: false
     default:
         description:
-        - Make the subvolume specified by I(name) the filesystem's default subvolume.
+        - Make the subvolume specified by O(name) the filesystem's default subvolume.
         type: bool
         default: false
     filesystem_device:
@@ -49,7 +49,7 @@ options:
     recursive:
         description:
         - When true, indicates that parent/child subvolumes should be created/removedas necessary
-          to complete the operation (for I(state=present) and I(state=absent) respectively).
+          to complete the operation (for O(state=present) and O(state=absent) respectively).
         type: bool
         default: false
     snapshot_source:
@@ -60,11 +60,11 @@ options:
     snapshot_conflict:
         description:
         - Policy defining behavior when a subvolume already exists at the path of the requested snapshot.
-        - C(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required.
+        - V(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required.
           Warning, this option does not yet verify that the target subvolume was generated from a snapshot of the requested source.
-        - C(clobber) - If a subvolume already exists at the requested location, delete it first.
+        - V(clobber) - If a subvolume already exists at the requested location, delete it first.
           This option is not idempotent and will result in a new snapshot being generated on every execution.
-        - C(error) - If a subvolume already exists at the requested location, return an error.
+        - V(error) - If a subvolume already exists at the requested location, return an error.
           This option is not idempotent and will result in an error on replay of the module.
         type: str
         choices: [ skip, clobber, error ]
@@ -77,7 +77,7 @@ options:
         default: present
 
 notes:
-  - If any or all of the options I(filesystem_device), I(filesystem_label) or I(filesystem_uuid) parameters are provided, there is expected
+  - If any or all of the options O(filesystem_device), O(filesystem_label) or O(filesystem_uuid) parameters are provided, there is expected
     to be a matching btrfs filesystem. If none are provided and only a single btrfs filesystem exists or only a single
     btrfs filesystem is mounted, that filesystem will be used; otherwise, the module will take no action and return an error.
 
@@ -201,7 +201,7 @@ modifications:
 
 target_subvolume_id:
     description:
-    - The ID of the subvolume specified with the I(name) parameter, either pre-existing or created as part of module execution.
+    - The ID of the subvolume specified with the O(name) parameter, either pre-existing or created as part of module execution.
     type: int
     sample: 257
     returned: Success and subvolume exists after module execution

plugins/modules/bzr.py

@@ -16,7 +16,7 @@ author:
 - André Paramés (@andreparames)
 short_description: Deploy software (or files) from bzr branches
 description:
-    - Manage I(bzr) branches to deploy files or software.
+    - Manage C(bzr) branches to deploy files or software.
 extends_documentation_fragment:
     - community.general.attributes
 attributes:
@@ -44,9 +44,9 @@ options:
         type: str
     force:
         description:
-            - If C(true), any modified files in the working
+            - If V(true), any modified files in the working
-              tree will be discarded.  Before 1.9 the default
+              tree will be discarded.  Before Ansible 1.9 the default
-              value was C(true).
+              value was V(true).
         type: bool
         default: false
     executable:

plugins/modules/cargo.py

@@ -35,12 +35,12 @@ options:
     description:
       ->
       The base path where to install the Rust packages. Cargo automatically appends
-      C(/bin). In other words, C(/usr/local) will become C(/usr/local/bin).
+      V(/bin). In other words, V(/usr/local) will become V(/usr/local/bin).
     type: path
   version:
     description:
       ->
-      The version to install. If I(name) contains multiple values, the module will
+      The version to install. If O(name) contains multiple values, the module will
       try to install all of them in this version.
     type: str
     required: false

plugins/modules/circonus_annotation.py

@@ -52,12 +52,12 @@ options:
         type: int
         description:
             - Unix timestamp of event start
-            - If not specified, it defaults to I(now).
+            - If not specified, it defaults to "now".
     stop:
         type: int
         description:
             - Unix timestamp of event end
-            - If not specified, it defaults to I(now) + I(duration).
+            - If not specified, it defaults to "now" + O(duration).
     duration:
         type: int
         description:

plugins/modules/cloudflare_dns.py

@@ -31,7 +31,7 @@ options:
     - API token.
     - Required for api token authentication.
     - "You can obtain your API token from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)."
-    - Can be specified in C(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0.
+    - Can be specified in E(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0.
     type: str
     required: false
     version_added: '0.2.0'
@@ -51,39 +51,39 @@ options:
   algorithm:
     description:
     - Algorithm number.
-    - Required for I(type=DS) and I(type=SSHFP) when I(state=present).
+    - Required for O(type=DS) and O(type=SSHFP) when O(state=present).
     type: int
   cert_usage:
     description:
     - Certificate usage number.
-    - Required for I(type=TLSA) when I(state=present).
+    - Required for O(type=TLSA) when O(state=present).
     type: int
     choices: [ 0, 1, 2, 3 ]
   hash_type:
     description:
     - Hash type number.
-    - Required for I(type=DS), I(type=SSHFP) and I(type=TLSA) when I(state=present).
+    - Required for O(type=DS), O(type=SSHFP) and O(type=TLSA) when O(state=present).
     type: int
     choices: [ 1, 2 ]
   key_tag:
     description:
     - DNSSEC key tag.
-    - Needed for I(type=DS) when I(state=present).
+    - Needed for O(type=DS) when O(state=present).
     type: int
   port:
     description:
     - Service port.
-    - Required for I(type=SRV) and I(type=TLSA).
+    - Required for O(type=SRV) and O(type=TLSA).
     type: int
   priority:
     description:
     - Record priority.
-    - Required for I(type=MX) and I(type=SRV)
+    - Required for O(type=MX) and O(type=SRV)
     default: 1
     type: int
   proto:
     description:
-    - Service protocol. Required for I(type=SRV) and I(type=TLSA).
+    - Service protocol. Required for O(type=SRV) and O(type=TLSA).
     - Common values are TCP and UDP.
     - Before Ansible 2.6 only TCP and UDP were available.
     type: str
@@ -95,26 +95,26 @@ options:
   record:
     description:
     - Record to add.
-    - Required if I(state=present).
+    - Required if O(state=present).
-    - Default is C(@) (e.g. the zone name).
+    - Default is V(@) (that is, the zone name).
     type: str
     default: '@'
     aliases: [ name ]
   selector:
     description:
     - Selector number.
-    - Required for I(type=TLSA) when I(state=present).
+    - Required for O(type=TLSA) when O(state=present).
     choices: [ 0, 1 ]
     type: int
   service:
     description:
     - Record service.
-    - Required for I(type=SRV).
+    - Required for O(type=SRV).
     type: str
   solo:
     description:
     - Whether the record should be the only one for that record type and record name.
-    - Only use with I(state=present).
+    - Only use with O(state=present).
     - This will delete all other records with the same record name and type.
     type: bool
   state:
@@ -136,20 +136,20 @@ options:
     default: 1
   type:
     description:
-      - The type of DNS record to create. Required if I(state=present).
+      - The type of DNS record to create. Required if O(state=present).
-      - I(type=DS), I(type=SSHFP) and I(type=TLSA) added in Ansible 2.7.
+      - O(type=DS), O(type=SSHFP), and O(type=TLSA) were added in Ansible 2.7.
     type: str
     choices: [ A, AAAA, CNAME, DS, MX, NS, SPF, SRV, SSHFP, TLSA, TXT ]
   value:
     description:
     - The record value.
-    - Required for I(state=present).
+    - Required for O(state=present).
     type: str
     aliases: [ content ]
   weight:
     description:
     - Service weight.
-    - Required for I(type=SRV).
+    - Required for O(type=SRV).
     type: int
     default: 1
   zone:

plugins/modules/cobbler_system.py

@@ -30,7 +30,7 @@ options:
   port:
     description:
     - Port number to be used for REST connection.
-    - The default value depends on parameter C(use_ssl).
+    - The default value depends on parameter I(use_ssl).
     type: int
   username:
     description:
@@ -43,13 +43,13 @@ options:
     type: str
   use_ssl:
     description:
-    - If C(false), an HTTP connection will be used instead of the default HTTPS connection.
+    - If V(false), an HTTP connection will be used instead of the default HTTPS connection.
     type: bool
     default: true
   validate_certs:
     description:
-    - If C(false), SSL certificates will not be validated.
+    - If V(false), SSL certificates will not be validated.
-    - This should only set to C(false) when used on personally controlled sites using self-signed certificates.
+    - This should only set to V(false) when used on personally controlled sites using self-signed certificates.
     type: bool
     default: true
   name:
@@ -144,11 +144,11 @@ EXAMPLES = r'''
 RETURN = r'''
 systems:
   description: List of systems
-  returned: I(state=query) and I(name) is not provided
+  returned: O(state=query) and O(name) is not provided
   type: list
 system:
   description: (Resulting) information about the system we are working with
-  returned: when I(name) is provided
+  returned: when O(name) is provided
   type: dict
 '''
 

plugins/modules/composer.py

@@ -49,7 +49,7 @@ options:
         description:
             - Directory of your project (see --working-dir). This is required when
               the command is not run globally.
-            - Will be ignored if I(global_command=true).
+            - Will be ignored if O(global_command=true).
     global_command:
         description:
             - Runs the specified command globally.
@@ -111,7 +111,7 @@ options:
         version_added: 3.2.0
 requirements:
     - php
-    - composer installed in bin path (recommended /usr/local/bin) or specified in I(composer_executable)
+    - composer installed in bin path (recommended /usr/local/bin) or specified in O(composer_executable)
 notes:
     - Default options that are always appended in each execution are --no-ansi, --no-interaction and --no-progress if available.
     - We received reports about issues on macOS if composer was installed by Homebrew. Please use the official install method to avoid issues.

plugins/modules/consul.py

@@ -21,8 +21,8 @@ description:
    notify the health of the entire node to the cluster.
    Service level checks do not require a check name or id as these are derived
    by Consul from the Service name and id respectively by appending 'service:'
-   Node level checks require a I(check_name) and optionally a I(check_id)."
+   Node level checks require a O(check_name) and optionally a O(check_id)."
- - Currently, there is no complete way to retrieve the script, interval or ttl
+ - Currently, there is no complete way to retrieve the script, interval or TTL
    metadata for a registered check. Without this metadata it is not possible to
    tell if the data supplied with ansible represents a change to a check. As a
    result this does not attempt to determine changes and will always report a
@@ -56,7 +56,7 @@ options:
     service_id:
         type: str
         description:
-          - The ID for the service, must be unique per node. If I(state=absent),
+          - The ID for the service, must be unique per node. If O(state=absent),
             defaults to the service name if supplied.
     host:
         type: str
@@ -86,12 +86,12 @@ options:
         type: int
         description:
           - The port on which the service is listening. Can optionally be supplied for
-            registration of a service, i.e. if I(service_name) or I(service_id) is set.
+            registration of a service, that is if O(service_name) or O(service_id) is set.
     service_address:
         type: str
         description:
           - The address to advertise that the service will be listening on.
-            This value will be passed as the I(address) parameter to Consul's
+            This value will be passed as the C(address) parameter to Consul's
             C(/v1/agent/service/register) API method, so refer to the Consul API
             documentation for further details.
     tags:
@@ -103,19 +103,19 @@ options:
         type: str
         description:
           - The script/command that will be run periodically to check the health of the service.
-          - Requires I(interval) to be provided.
+          - Requires O(interval) to be provided.
     interval:
         type: str
         description:
           - The interval at which the service check will be run.
-            This is a number with a C(s) or C(m) suffix to signify the units of seconds or minutes e.g C(15s) or C(1m).
+            This is a number with a V(s) or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m).
-            If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s).
+            If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
-          - Required if one of the parameters I(script), I(http), or I(tcp) is specified.
+          - Required if one of the parameters O(script), O(http), or O(tcp) is specified.
     check_id:
         type: str
         description:
-          - An ID for the service check. If I(state=absent), defaults to
+          - An ID for the service check. If O(state=absent), defaults to
-            I(check_name). Ignored if part of a service definition.
+            O(check_name). Ignored if part of a service definition.
     check_name:
         type: str
         description:
@@ -124,34 +124,34 @@ options:
     ttl:
         type: str
         description:
-          - Checks can be registered with a ttl instead of a I(script) and I(interval)
+          - Checks can be registered with a TTL instead of a O(script) and O(interval)
             this means that the service will check in with the agent before the
-            ttl expires. If it doesn't the check will be considered failed.
+            TTL expires. If it doesn't the check will be considered failed.
             Required if registering a check and the script an interval are missing
-            Similar to the interval this is a number with a C(s) or C(m) suffix to
+            Similar to the interval this is a number with a V(s) or V(m) suffix to
-            signify the units of seconds or minutes e.g C(15s) or C(1m).
+            signify the units of seconds or minutes, for example V(15s) or V(1m).
-            If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s).
+            If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
     tcp:
         type: str
         description:
           - Checks can be registered with a TCP port. This means that consul
             will check if the connection attempt to that port is successful (that is, the port is currently accepting connections).
-            The format is C(host:port), for example C(localhost:80).
+            The format is V(host:port), for example V(localhost:80).
-          - Requires I(interval) to be provided.
+          - Requires O(interval) to be provided.
         version_added: '1.3.0'
     http:
         type: str
         description:
           - Checks can be registered with an HTTP endpoint. This means that consul
             will check that the http endpoint returns a successful HTTP status.
-          - Requires I(interval) to be provided.
+          - Requires O(interval) to be provided.
     timeout:
         type: str
         description:
           - A custom HTTP check timeout. The consul default is 10 seconds.
-            Similar to the interval this is a number with a C(s) or C(m) suffix to
+            Similar to the interval this is a number with a V(s) or V(m) suffix to
-            signify the units of seconds or minutes, e.g. C(15s) or C(1m).
+            signify the units of seconds or minutes, for example V(15s) or V(1m).
-            If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s).
+            If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
     token:
         type: str
         description:
@@ -159,7 +159,7 @@ options:
     ack_params_state_absent:
         type: bool
         description:
-          - Disable deprecation warning when using parameters incompatible with I(state=absent).
+          - Disable deprecation warning when using parameters incompatible with O(state=absent).
 '''
 
 EXAMPLES = '''

plugins/modules/consul_acl.py

@@ -156,7 +156,7 @@ token:
 rules:
     description: the HCL JSON representation of the rules associated to the ACL, in the format described in the
                  Consul documentation (https://www.consul.io/docs/guides/acl.html#rule-specification).
-    returned: I(status) == "present"
+    returned: when O(state=present)
     type: dict
     sample: {
         "key": {

plugins/modules/consul_kv.py

@@ -17,7 +17,7 @@ description:
   - Allows the retrieval, addition, modification and deletion of key/value entries in a
     consul cluster via the agent. The entire contents of the record, including
     the indices, flags and session are returned as C(value).
-  - If the C(key) represents a prefix then note that when a value is removed, the existing
+  - If the O(key) represents a prefix then note that when a value is removed, the existing
     value if any is returned as part of the results.
   - See http://www.consul.io/docs/agent/http.html#kv for more details.
 requirements:
@@ -36,14 +36,14 @@ attributes:
 options:
     state:
         description:
-          - The action to take with the supplied key and value. If the state is C(present) and I(value) is set, the key
+          - The action to take with the supplied key and value. If the state is V(present) and O(value) is set, the key
-            contents will be set to the value supplied and C(changed) will be set to C(true) only if the value was
+            contents will be set to the value supplied and C(changed) will be set to V(true) only if the value was
-            different to the current contents. If the state is C(present) and I(value) is not set, the existing value
+            different to the current contents. If the state is V(present) and O(value) is not set, the existing value
-            associated to the key will be returned. The state C(absent) will remove the key/value pair,
+            associated to the key will be returned. The state V(absent) will remove the key/value pair,
-            again C(changed) will be set to true only if the key actually existed
+            again C(changed) will be set to V(true) only if the key actually existed
             prior to the removal. An attempt can be made to obtain or free the
-            lock associated with a key/value pair with the states C(acquire) or
+            lock associated with a key/value pair with the states V(acquire) or
-            C(release) respectively. a valid session must be supplied to make the
+            V(release) respectively. a valid session must be supplied to make the
             attempt changed will be true if the attempt is successful, false
             otherwise.
         type: str
@@ -56,17 +56,17 @@ options:
         required: true
     value:
         description:
-          - The value should be associated with the given key, required if C(state)
+          - The value should be associated with the given key, required if O(state)
-            is C(present).
+            is V(present).
         type: str
     recurse:
         description:
           - If the key represents a prefix, each entry with the prefix can be
-            retrieved by setting this to C(true).
+            retrieved by setting this to V(true).
         type: bool
     retrieve:
         description:
-            - If the I(state) is C(present) and I(value) is set, perform a
+            - If the O(state) is V(present) and O(value) is set, perform a
               read after setting the value and return this value.
         default: true
         type: bool
@@ -82,9 +82,9 @@ options:
         type: str
     cas:
         description:
-          - Used when acquiring a lock with a session. If the C(cas) is C(0), then
+          - Used when acquiring a lock with a session. If the O(cas) is V(0), then
             Consul will only put the key if it does not already exist. If the
-            C(cas) value is non-zero, then the key is only set if the index matches
+            O(cas) value is non-zero, then the key is only set if the index matches
             the ModifyIndex of that key.
         type: str
     flags:

plugins/modules/consul_session.py

@@ -31,25 +31,25 @@ attributes:
 options:
     id:
         description:
-          - ID of the session, required when I(state) is either C(info) or
+          - ID of the session, required when O(state) is either V(info) or
-            C(remove).
+            V(remove).
         type: str
     state:
         description:
           - Whether the session should be present i.e. created if it doesn't
-            exist, or absent, removed if present. If created, the I(id) for the
+            exist, or absent, removed if present. If created, the O(id) for the
-            session is returned in the output. If C(absent), I(id) is
+            session is returned in the output. If V(absent), O(id) is
             required to remove the session. Info for a single session, all the
             sessions for a node or all available sessions can be retrieved by
-            specifying C(info), C(node) or C(list) for the I(state); for C(node)
+            specifying V(info), V(node) or V(list) for the O(state); for V(node)
-            or C(info), the node I(name) or session I(id) is required as parameter.
+            or V(info), the node O(name) or session O(id) is required as parameter.
         choices: [ absent, info, list, node, present ]
         type: str
         default: present
     name:
         description:
           - The name that should be associated with the session. Required when
-            I(state=node) is used.
+            O(state=node) is used.
         type: str
     delay:
         description:

plugins/modules/cpanm.py

@@ -27,8 +27,8 @@ options:
   name:
     type: str
     description:
-      - The Perl library to install. Valid values change according to the I(mode), see notes for more details.
+      - The Perl library to install. Valid values change according to the O(mode), see notes for more details.
-      - Note that for installing from a local path the parameter I(from_path) should be used.
+      - Note that for installing from a local path the parameter O(from_path) should be used.
     aliases: [pkg]
   from_path:
     type: path
@@ -59,7 +59,7 @@ options:
     default: false
   version:
     description:
-      - Version specification for the perl module. When I(mode) is C(new), C(cpanm) version operators are accepted.
+      - Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted.
     type: str
   executable:
     description:
@@ -68,32 +68,24 @@ options:
   mode:
     description:
       - Controls the module behavior. See notes below for more details.
-      - Default is C(compatibility) but that behavior is deprecated and will be changed to C(new) in community.general 9.0.0.
+      - Default is V(compatibility) but that behavior is deprecated and will be changed to V(new) in community.general 9.0.0.
     type: str
     choices: [compatibility, new]
     version_added: 3.0.0
   name_check:
     description:
-      - When in C(new) mode, this parameter can be used to check if there is a module I(name) installed (at I(version), when specified).
+      - When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified).
     type: str
     version_added: 3.0.0
 notes:
   - Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host.
-  - "This module now comes with a choice of execution I(mode): C(compatibility) or C(new)."
+  - "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)."
-  - "C(compatibility) mode:"
+  - "O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility. This is the default mode.
-  - When using C(compatibility) mode, the module will keep backward compatibility. This is the default mode.
+    O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version)
-  - I(name) must be either a module name or a distribution file.
+    when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL.
-  - >
+    C(cpanm) version specifiers do not work in this mode."
-    If the perl module given by I(name) is installed (at the exact I(version) when specified), then nothing happens.
+  - "O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file,
-    Otherwise, it will be installed using the C(cpanm) executable.
+    a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized."
-  - I(name) cannot be an URL, or a git URL.
-  - C(cpanm) version specifiers do not work in this mode.
-  - "C(new) mode:"
-  - "When using C(new) mode, the module will behave differently"
-  - >
-    The I(name) parameter may refer to a module name, a distribution file,
-    a HTTP URL or a git repository URL as described in C(cpanminus) documentation.
-  - C(cpanm) version specifiers are recognized.
 author:
   - "Franck Cuny (@fcuny)"
   - "Alexei Znamensky (@russoz)"

plugins/modules/cronvar.py

@@ -40,16 +40,16 @@ options:
   value:
     description:
       - The value to set this variable to.
-      - Required if I(state=present).
+      - Required if O(state=present).
     type: str
   insertafter:
     description:
       - If specified, the variable will be inserted after the variable specified.
-      - Used with I(state=present).
+      - Used with O(state=present).
     type: str
   insertbefore:
     description:
-      - Used with I(state=present). If specified, the variable will be inserted
+      - Used with O(state=present). If specified, the variable will be inserted
         just before the variable specified.
     type: str
   state:
@@ -61,18 +61,19 @@ options:
   user:
     description:
       - The specific user whose crontab should be modified.
-      - This parameter defaults to C(root) when unset.
+      - This parameter defaults to V(root) when unset.
     type: str
   cron_file:
     description:
       - If specified, uses this file instead of an individual user's crontab.
-      - Without a leading C(/), this is assumed to be in I(/etc/cron.d).
+      - Without a leading V(/), this is assumed to be in C(/etc/cron.d).
-      - With a leading C(/), this is taken as absolute.
+      - With a leading V(/), this is taken as absolute.
     type: str
   backup:
     description:
       - If set, create a backup of the crontab before it is modified.
         The location of the backup is returned in the C(backup) variable by this module.
+      # TODO: C() above should be RV(), but return values have not been documented!
     type: bool
     default: false
 requirements:

plugins/modules/crypttab.py

@@ -25,38 +25,38 @@ options:
   name:
     description:
       - Name of the encrypted block device as it appears in the C(/etc/crypttab) file, or
-        optionally prefixed with C(/dev/mapper/), as it appears in the filesystem. I(/dev/mapper/)
+        optionally prefixed with V(/dev/mapper/), as it appears in the filesystem. V(/dev/mapper/)
-        will be stripped from I(name).
+        will be stripped from O(name).
     type: str
     required: true
   state:
     description:
-      - Use I(present) to add a line to C(/etc/crypttab) or update its definition
+      - Use V(present) to add a line to C(/etc/crypttab) or update its definition
         if already present.
-      - Use I(absent) to remove a line with matching I(name).
+      - Use V(absent) to remove a line with matching O(name).
-      - Use I(opts_present) to add options to those already present; options with
+      - Use V(opts_present) to add options to those already present; options with
         different values will be updated.
-      - Use I(opts_absent) to remove options from the existing set.
+      - Use V(opts_absent) to remove options from the existing set.
     type: str
     required: true
     choices: [ absent, opts_absent, opts_present, present ]
   backing_device:
     description:
       - Path to the underlying block device or file, or the UUID of a block-device
-        prefixed with I(UUID=).
+        prefixed with V(UUID=).
     type: str
   password:
     description:
       - Encryption password, the path to a file containing the password, or
-        C(-) or unset if the password should be entered at boot.
+        V(-) or unset if the password should be entered at boot.
     type: path
   opts:
     description:
-      - A comma-delimited list of options. See C(crypttab(5) ) for details.
+      - A comma-delimited list of options. See V(crypttab(5\)) for details.
     type: str
   path:
     description:
-      - Path to file to use instead of C(/etc/crypttab).
+      - Path to file to use instead of V(/etc/crypttab).
       - This might be useful in a chroot environment.
     type: path
     default: /etc/crypttab