doc style adjustments: modules [ab]* (#10350)

* doc style adjustments: modules [ab]*

* Update plugins/modules/btrfs_subvolume.py

* Update plugins/modules/aerospike_migrations.py

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

* Update plugins/modules/aix_filesystem.py

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

* Update plugins/modules/bigpanda.py

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

* aix_filesystems: roll back wording for `filesystem` description

---------

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

plugins/modules/aerospike_migrations.py

@@ -70,7 +70,7 @@ options:
     type: bool
   min_cluster_size:
     description:
-      - Check will return bad until cluster size is met or until tries is exhausted.
+      - Check fails until cluster size is met or until tries is exhausted.
     required: false
     type: int
     default: 1
@@ -94,10 +94,10 @@ options:
     default: migrate_rx_partitions_remaining
   target_cluster_size:
     description:
-      - When all aerospike builds in the cluster are greater than version 4.3, then the C(cluster-stable) info command will
+      - When all aerospike builds in the cluster are greater than version 4.3, then the C(cluster-stable) info command is
-        be used. Inside this command, you can optionally specify what the target cluster size is - but it is not necessary.
+        used. Inside this command, you can optionally specify what the target cluster size is - but it is not necessary.
         You can still rely on O(min_cluster_size) if you do not want to use this option.
-      - If this option is specified on a cluster that has at least one host <4.3 then it will be ignored until the min version
+      - If this option is specified on a cluster that has at least one host <4.3 then it is ignored until the min version
         reaches 4.3.
     required: false
     type: int

plugins/modules/airbrake_deployment.py

@@ -71,7 +71,7 @@ options:
     type: str
   validate_certs:
     description:
-      - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled
+      - If V(false), SSL certificates for the target URL is not validated. This should only be used on personally controlled
         sites using self-signed certificates.
     required: false
     default: true

plugins/modules/aix_filesystem.py

@@ -47,7 +47,7 @@ options:
     description:
       - Logical volume (LV) device name or remote export device to create a NFS file system.
       - It is used to create a file system on an already existing logical volume or the exported NFS file system.
-      - If not mentioned a new logical volume name will be created following AIX standards (LVM).
+      - If not mentioned a new logical volume name is created following AIX standards (LVM).
     type: str
   fs_type:
     description:
@@ -81,14 +81,14 @@ options:
   size:
     description:
       - Specifies the file system size.
-      - For already V(present) it will be resized.
+      - For already present it resizes the filesystem.
-      - 512-byte blocks, Megabytes or Gigabytes. If the value has M specified it will be in Megabytes. If the value has G
+      - 512-byte blocks, megabytes or gigabytes. If the value has M specified it is in megabytes. If the value has G specified
-        specified it will be in Gigabytes.
+        it is in gigabytes.
-      - If no M or G the value will be 512-byte blocks.
+      - If no M or G the value is 512-byte blocks.
-      - If "+" is specified in begin of value, the value will be added.
+      - If V(+) is specified in begin of value, the value is added.
-      - If "-" is specified in begin of value, the value will be removed.
+      - If V(-) is specified in begin of value, the value is removed.
-      - If "+" or "-" is not specified, the total value will be the specified.
+      - If neither V(+) nor V(-) is specified, then the total value is the specified.
-      - Size will respects the LVM AIX standards.
+      - Size respects the LVM AIX standards.
     type: str
   state:
     description:

plugins/modules/aix_lvg.py

@@ -36,7 +36,7 @@ options:
     description:
       - List of comma-separated devices to use as physical devices in this volume group.
       - Required when creating or extending (V(present) state) the volume group.
-      - If not informed reducing (V(absent) state) the volume group will be removed.
+      - If not informed reducing (V(absent) state) the volume group is removed.
     type: list
     elements: str
   state:
@@ -57,7 +57,7 @@ options:
     choices: [big, normal, scalable]
     default: normal
 notes:
-  - AIX will permit remove VG only if all LV/Filesystems are not busy.
+  - AIX allows removing VG only if all LV/Filesystems are not busy.
   - Module does not modify PP size for already present volume group.
 """
 

plugins/modules/ali_instance.py

@@ -45,8 +45,7 @@ options:
     type: str
   availability_zone:
     description:
-      - Aliyun availability zone ID in which to launch the instance. If it is not specified, it will be allocated by system
+      - Aliyun availability zone ID in which to launch the instance. If it is not specified, it is allocated by system automatically.
-        automatically.
     aliases: ['alicloud_zone', 'zone_id']
     type: str
   image_id:
@@ -109,7 +108,7 @@ options:
     version_added: '0.2.0'
   password:
     description:
-      - The password to login instance. After rebooting instances, modified password will take effect.
+      - The password to login instance. After rebooting instances, modified password is effective.
     type: str
   system_disk_category:
     description:
@@ -140,7 +139,7 @@ options:
     description:
       - 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 O(tags) option. If it is not specified, it will be replaced by O(instance_name).
+        the O(tags) option. If it is not specified, it is replaced by O(instance_name).
     type: str
   allocate_public_ip:
     description:
@@ -172,8 +171,7 @@ options:
     type: int
   instance_ids:
     description:
-      - A list of instance IDs. It is required when need to operate existing instances. If it is specified, O(count) will
+      - A list of instance IDs. It is required when need to operate existing instances. If it is specified, O(count) is ignored.
-        lose efficacy.
     type: list
     elements: str
   force:
@@ -203,7 +201,7 @@ options:
   user_data:
     description:
       - User-defined data to customize the startup behaviors of an ECS instance and to pass data into an ECS instance. It
-        only will take effect when launching the new ECS instances.
+        only takes effect when launching the new ECS instances.
     required: false
     type: str
   ram_role_name:
@@ -226,7 +224,7 @@ options:
     version_added: '0.2.0'
   period_unit:
     description:
-      - The duration unit that you will buy the resource. It is valid when O(instance_charge_type=PrePaid).
+      - The duration unit that you are buying the resource. It is valid when O(instance_charge_type=PrePaid).
     choices: ['Month', 'Week']
     default: 'Month'
     type: str
@@ -424,7 +422,7 @@ instances:
           type: str
           sample: 42.10.2.2
     expired_time:
-      description: The time the instance will expire.
+      description: The time the instance expires.
       returned: always
       type: str
       sample: "2099-12-31T15:59Z"
@@ -615,7 +613,7 @@ ids:
   description: List of ECS instance IDs.
   returned: always
   type: list
-  sample: [i-12345er, i-3245fs]
+  sample: ["i-12345er", "i-3245fs"]
 """
 
 import re

plugins/modules/ali_instance_info.py

@@ -167,7 +167,7 @@ instances:
           type: str
           sample: 42.10.2.2
     expired_time:
-      description: The time the instance will expire.
+      description: The time the instance expires.
       returned: always
       type: str
       sample: "2099-12-31T15:59Z"
@@ -341,7 +341,7 @@ ids:
   description: List of ECS instance IDs.
   returned: always
   type: list
-  sample: [i-12345er, i-3245fs]
+  sample: ["i-12345er", "i-3245fs"]
 """
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib

plugins/modules/android_sdk.py

@@ -28,8 +28,8 @@ version_added: 10.2.0
 options:
   accept_licenses:
     description:
-      - If this is set to V(true), the module will try to accept license prompts generated by C(sdkmanager) during package
+      - If this is set to V(true), the module attempts to accept license prompts generated by C(sdkmanager) during package
-        installation. Otherwise, every license prompt will be rejected.
+        installation. Otherwise, every license prompt is rejected.
     type: bool
     default: false
   name:
@@ -64,16 +64,16 @@ requirements:
 notes:
   - For some of the packages installed by C(sdkmanager) is it necessary to accept licenses. Usually it is done through command
     line prompt in a form of a Y/N question when a licensed package is requested to be installed. If there are several packages
-    requested for installation and at least two of them belong to different licenses, the C(sdkmanager) tool will prompt for
+    requested for installation and at least two of them belong to different licenses, the C(sdkmanager) tool prompts for these
-    these licenses in a loop. In order to install packages, the module must be able to answer these license prompts. Currently,
+    licenses in a loop. In order to install packages, the module must be able to answer these license prompts. Currently,
     it is only possible to answer one license prompt at a time, meaning that instead of installing multiple packages as a
-    single invocation of the C(sdkmanager --install) command, it will be done by executing the command independently for each
+    single invocation of the C(sdkmanager --install) command, it is done by executing the command independently for each package.
-    package. This makes sure that at most only one license prompt will need to be answered. At the time of writing this module,
+    This makes sure that at most only one license prompt needs to be answered. At the time of writing this module, a C(sdkmanager)'s
-    a C(sdkmanager)'s package may belong to at most one license type that needs to be accepted. However, if this changes in
+    package may belong to at most one license type that needs to be accepted. However, if this changes in the future, the
-    the future, the module may hang as there might be more prompts generated by the C(sdkmanager) tool which the module will
+    module may hang as there might be more prompts generated by the C(sdkmanager) tool which the module is unable to answer.
-    not be able to answer. If this becomes the case, file an issue and in the meantime, consider accepting all the licenses
+    If this becomes the case, file an issue and in the meantime, consider accepting all the licenses in advance, as it is
-    in advance, as it is described in the C(sdkmanager) L(documentation,https://developer.android.com/tools/sdkmanager#accept-licenses),
+    described in the C(sdkmanager) L(documentation,https://developer.android.com/tools/sdkmanager#accept-licenses), for instance,
-    for instance, using the M(ansible.builtin.command) module.
+    using the M(ansible.builtin.command) module.
 seealso:
   - name: sdkmanager tool documentation
     description: Detailed information of how to install and use sdkmanager command line tool.
@@ -126,13 +126,13 @@ installed:
   description: A list of packages that have been installed.
   returned: when packages have changed
   type: list
-  sample: ['build-tools;34.0.0', 'platform-tools']
+  sample: ["build-tools;34.0.0", "platform-tools"]
 
 removed:
   description: A list of packages that have been removed.
   returned: when packages have changed
   type: list
-  sample: ['build-tools;34.0.0', 'platform-tools']
+  sample: ["build-tools;34.0.0", "platform-tools"]
 """
 
 from ansible_collections.community.general.plugins.module_utils.mh.module_helper import StateModuleHelper

plugins/modules/ansible_galaxy_install.py

@@ -18,8 +18,8 @@ description:
   - This module allows the installation of Ansible collections or roles using C(ansible-galaxy).
 notes:
   - Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0.
-  - The module will try and run using the C(C.UTF-8) locale. If that fails, it will try C(en_US.UTF-8). If that one also fails,
+  - The module tries to run using the C(C.UTF-8) locale. If that fails, it tries C(en_US.UTF-8). If that one also fails, the
-    the module will fail.
+    module fails.
 seealso:
   - name: C(ansible-galaxy) command manual page
     description: Manual page for the command.
@@ -37,10 +37,10 @@ attributes:
 options:
   state:
     description:
-      - If O(state=present) then the collection or role will be installed. Note that the collections and roles are not updated
+      - If O(state=present) then the collection or role is installed. Note that the collections and roles are not updated
         with this option.
-      - Currently the O(state=latest) is ignored unless O(type=collection), and it will ensure the collection is installed
+      - Currently the O(state=latest) is ignored unless O(type=collection), and it ensures the collection is installed and
-        and updated to the latest available version.
+        updated to the latest available version.
       - Please note that O(force=true) can be used to perform upgrade regardless of O(type).
     type: str
     choices: [present, latest]
@@ -71,7 +71,7 @@ options:
   dest:
     description:
       - 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 O(type=both), when O(requirements_file) contains
+      - Please notice that C(ansible-galaxy) does not install collections with O(type=both), when O(requirements_file) contains
         both roles and collections and O(dest) is specified.
     type: path
   no_deps:
@@ -83,7 +83,7 @@ options:
   force:
     description:
       - Force overwriting existing roles and/or collections.
-      - It can be used for upgrading, but the module output will always report C(changed=true).
+      - It can be used for upgrading, but the module output always reports C(changed=true).
       - Using O(force=true) is mandatory when downgrading.
     type: bool
     default: false

plugins/modules/apk.py

@@ -47,8 +47,8 @@ options:
     version_added: 1.0.0
   repository:
     description:
-      - A package repository or multiple repositories. Unlike with the underlying apk command, this list will override the
+      - A package repository or multiple repositories. Unlike with the underlying apk command, this list overrides the system
-        system repositories rather than supplement them.
+        repositories rather than supplement them.
     type: list
     elements: str
   state:
@@ -79,7 +79,7 @@ options:
     version_added: 5.4.0
 notes:
   - 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
+  - When used with a C(loop:) each package is processed individually, it is much more efficient to pass the list directly
     to the O(name) option.
 """
 
@@ -164,7 +164,7 @@ packages:
   description: A list of packages that have been changed.
   returned: when packages have changed
   type: list
-  sample: ['package', 'other-package']
+  sample: ["package", "other-package"]
 """
 
 import re

plugins/modules/apt_rpm.py

@@ -36,8 +36,8 @@ options:
     description:
       - Indicates the desired package state.
       - The states V(latest) and V(present_not_latest) have been added in community.general 8.6.0.
-      - Please note before community.general 11.0.0, V(present) and V(installed) were equivalent to V(latest).
+      - Please note before community.general 11.0.0, V(present) and V(installed) were equivalent to V(latest). This changed
-        This changed in community.general 11.0.0. Now they are equivalent to V(present_not_latest).
+        in community.general 11.0.0. Now they are equivalent to V(present_not_latest).
     choices:
       - absent
       - present

plugins/modules/archive.py

@@ -43,7 +43,7 @@ options:
       - The file name of the destination archive. The parent directory must exists on the remote host.
       - 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.
+      - If the destination archive already exists, it is truncated and overwritten.
     type: path
   exclude_path:
     description:

plugins/modules/awall.py

@@ -40,7 +40,7 @@ options:
     description:
       - Activate the new firewall rules.
       - Can be run with other steps or on its own.
-      - Idempotency is affected if O(activate=true), as the module will always report a changed state.
+      - Idempotency is affected if O(activate=true), as the module always reports a changed state.
     type: bool
     default: false
 notes:

plugins/modules/beadm.py

@@ -32,7 +32,7 @@ options:
     aliases: ["be"]
   snapshot:
     description:
-      - If specified, the new boot environment will be cloned from the given snapshot or inactive boot environment.
+      - If specified, the new boot environment is cloned from the given snapshot or inactive boot environment.
     type: str
   description:
     description:

plugins/modules/bearychat.py

@@ -33,7 +33,7 @@ options:
       - Message to send.
   markdown:
     description:
-      - If V(true), text will be parsed as markdown.
+      - If V(true), text is parsed as markdown.
     default: true
     type: bool
   channel:

plugins/modules/bigpanda.py

@@ -75,7 +75,7 @@ options:
     default: "https://api.bigpanda.io"
   validate_certs:
     description:
-      - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled
+      - If V(false), SSL certificates for the target URL are not validated. This should only be used on personally controlled
         sites using self-signed certificates.
     required: false
     default: true

plugins/modules/bitbucket_pipeline_known_host.py

@@ -13,8 +13,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 O(key) field to specify it
+  - The host fingerprint is retrieved automatically, but in case of an error, one can use O(key) field to specify it manually.
-    manually.
 author:
   - Evgeniy Krysanov (@catcombo)
 extends_documentation_fragment:

plugins/modules/bootc_manage.py

@@ -20,7 +20,7 @@ options:
   state:
     description:
       - Control whether to apply the latest image or switch the image.
-      - B(Note:) This will not reboot the system.
+      - B(Note:) This does not reboot the system.
       - Please use M(ansible.builtin.reboot) to reboot the system.
     required: true
     type: str

plugins/modules/btrfs_info.py

@@ -64,7 +64,7 @@ filesystems:
         mountpoints:
           description: Paths where the subvolume is mounted on the targeted host.
           type: list
-          sample: ['/home']
+          sample: ["/home"]
         parent:
           description: The identifier of this subvolume's parent.
           type: int

plugins/modules/btrfs_subvolume.py

@@ -64,9 +64,9 @@ options:
         no change is required. Warning, this option does not yet verify that the target subvolume was generated from a snapshot
         of the requested source.
       - 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.
+        and results in a new snapshot being generated on every execution.
       - 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.
+        and results in an error on replay of the module.
     type: str
     choices: [skip, clobber, error]
     default: skip
@@ -80,8 +80,8 @@ options:
 notes:
   - 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
+    only a single btrfs filesystem is mounted, that filesystem is used; otherwise, the module takes no action and returns an
-    return an error.
+    error.
 extends_documentation_fragment:
   - community.general.attributes
 
@@ -180,7 +180,7 @@ filesystem:
         mountpoints:
           description: Paths where the subvolume is mounted on the targeted host.
           type: list
-          sample: ['/home']
+          sample: ["/home"]
         parent:
           description: The identifier of this subvolume's parent.
           type: int

plugins/modules/bundler.py

@@ -36,13 +36,13 @@ options:
     type: path
     description:
       - The directory to execute the bundler commands from. This directory needs to contain a valid Gemfile or .bundle/ directory.
-      - If not specified, it will default to the temporary working directory.
+      - If not specified, it defaults to the temporary working directory.
   exclude_groups:
     type: list
     elements: str
     description:
       - A list of Gemfile groups to exclude during operations. This only applies when O(state=present). Bundler considers
-        this a 'remembered' property for the Gemfile and will automatically exclude groups in future operations even if O(exclude_groups)
+        this a 'remembered' property for the Gemfile and automatically excludes groups in future operations even if O(exclude_groups)
         is not set.
   clean:
     description:
@@ -53,7 +53,7 @@ options:
     type: path
     description:
       - Only applies if O(state=present). The path to the gemfile to use to install gems.
-      - If not specified it will default to the Gemfile in current directory.
+      - If not specified it defaults to the Gemfile in current directory.
   local:
     description:
       - If set only installs gems from the cache on the target host.
@@ -61,8 +61,8 @@ options:
     default: false
   deployment_mode:
     description:
-      - Only applies if O(state=present). If set it will install gems in C(./vendor/bundle) instead of the default location.
+      - Only applies if O(state=present). If set it installs gems in C(./vendor/bundle) instead of the default location. Requires
-        Requires a C(Gemfile.lock) file to have been created prior.
+        a C(Gemfile.lock) file to have been created prior.
     type: bool
     default: false
   user_install:
@@ -75,12 +75,12 @@ options:
     description:
       - Only applies if O(state=present). Specifies the directory to install the gems into. If O(chdir) is set then this path
         is relative to O(chdir).
-      - If not specified the default RubyGems gem paths will be used.
+      - If not specified the default RubyGems gem paths are used.
   binstub_directory:
     type: path
     description:
       - Only applies if O(state=present). Specifies the directory to install any gem bins files to. When executed the bin
-        files will run within the context of the Gemfile and fail if any required gem dependencies are not installed. If O(chdir)
+        files run within the context of the Gemfile and fail if any required gem dependencies are not installed. If O(chdir)
         is set then this path is relative to O(chdir).
   extra_args:
     type: str

plugins/modules/bzr.py

@@ -42,12 +42,12 @@ options:
     type: str
   force:
     description:
-      - If V(true), any modified files in the working tree will be discarded.
+      - If V(true), any modified files in the working tree is discarded.
     type: bool
     default: false
   executable:
     description:
-      - Path to bzr executable to use. If not supplied, the normal mechanism for resolving binary paths will be used.
+      - Path to C(bzr) executable to use. If not supplied, the normal mechanism for resolving binary paths is used.
     type: str
 """