[PR #8664/c0fd10e7 backport][stable-9] Various docs improvements (#8666)

Various docs improvements (#8664)

Various docs improvements.

(cherry picked from commit c0fd10e793)

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

plugins/modules/haproxy.py

@@ -65,9 +65,8 @@ options:
   state:
     description:
       - Desired state of the provided backend host.
-      - Note that V(drain) state was added in version 2.4.
+      - Note that V(drain) state is supported only by HAProxy version 1.5 or later.
-      - It is supported only by HAProxy version 1.5 or later,
+        When used on versions < 1.5, it will be ignored.
-      - When used on versions < 1.5, it will be ignored.
     type: str
     required: true
     choices: [ disabled, drain, enabled ]

plugins/modules/ipa_dnsrecord.py

@@ -35,11 +35,8 @@ options:
   record_type:
     description:
     - The type of DNS record name.
-    - Currently, 'A', 'AAAA', 'A6', 'CNAME', 'DNAME', 'NS', 'PTR', 'TXT', 'SRV', 'MX' and 'SSHFP' are supported.
+    - Support for V(NS) was added in comunity.general 8.2.0.
-    - "'A6', 'CNAME', 'DNAME' and 'TXT' are added in version 2.5."
+    - Support for V(SSHFP) was added in community.general 9.1.0.
-    - "'SRV' and 'MX' are added in version 2.8."
-    - "'NS' are added in comunity.general 8.2.0."
-    - "'SSHFP' are added in community.general 9.1.0."
     required: false
     default: 'A'
     choices: ['A', 'AAAA', 'A6', 'CNAME', 'DNAME', 'MX', 'NS', 'PTR', 'SRV', 'TXT', 'SSHFP']
@@ -49,31 +46,31 @@ options:
     - Manage DNS record name with this value.
     - Mutually exclusive with O(record_values), and exactly one of O(record_value) and O(record_values) has to be specified.
     - Use O(record_values) if you need to specify multiple values.
-    - In the case of 'A' or 'AAAA' record types, this will be the IP address.
+    - In the case of V(A) or V(AAAA) record types, this will be the IP address.
-    - In the case of 'A6' record type, this will be the A6 Record data.
+    - In the case of V(A6) record type, this will be the A6 Record data.
-    - In the case of 'CNAME' record type, this will be the hostname.
+    - In the case of V(CNAME) record type, this will be the hostname.
-    - In the case of 'DNAME' record type, this will be the DNAME target.
+    - In the case of V(DNAME) record type, this will be the DNAME target.
-    - In the case of 'NS' record type, this will be the name server hostname. Hostname must already have a valid A or AAAA record.
+    - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA record.
-    - In the case of 'PTR' record type, this will be the hostname.
+    - In the case of V(PTR) record type, this will be the hostname.
-    - In the case of 'TXT' record type, this will be a text.
+    - In the case of V(TXT) record type, this will be a text.
-    - In the case of 'SRV' record type, this will be a service record.
+    - In the case of V(SRV) record type, this will be a service record.
-    - In the case of 'MX' record type, this will be a mail exchanger record.
+    - In the case of V(MX) record type, this will be a mail exchanger record.
-    - In the case of 'SSHFP' record type, this will be an SSH fingerprint record.
+    - In the case of V(SSHFP) record type, this will be an SSH fingerprint record.
     type: str
   record_values:
     description:
     - Manage DNS record name with this value.
     - Mutually exclusive with O(record_value), and exactly one of O(record_value) and O(record_values) has to be specified.
-    - In the case of 'A' or 'AAAA' record types, this will be the IP address.
+    - In the case of V(A) or V(AAAA) record types, this will be the IP address.
-    - In the case of 'A6' record type, this will be the A6 Record data.
+    - In the case of V(A6) record type, this will be the A6 Record data.
-    - In the case of 'CNAME' record type, this will be the hostname.
+    - In the case of V(CNAME) record type, this will be the hostname.
-    - In the case of 'DNAME' record type, this will be the DNAME target.
+    - In the case of V(DNAME) record type, this will be the DNAME target.
-    - In the case of 'NS' record type, this will be the name server hostname. Hostname must already have a valid A or AAAA record.
+    - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA record.
-    - In the case of 'PTR' record type, this will be the hostname.
+    - In the case of V(PTR) record type, this will be the hostname.
-    - In the case of 'TXT' record type, this will be a text.
+    - In the case of V(TXT) record type, this will be a text.
-    - In the case of 'SRV' record type, this will be a service record.
+    - In the case of V(SRV) record type, this will be a service record.
-    - In the case of 'MX' record type, this will be a mail exchanger record.
+    - In the case of V(MX) record type, this will be a mail exchanger record.
-    - In the case of 'SSHFP' record type, this will be an SSH fingerprint record.
+    - In the case of V(SSHFP) record type, this will be an SSH fingerprint record.
     type: list
     elements: str
   record_ttl:

plugins/modules/maven_artifact.py

@@ -11,7 +11,7 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: maven_artifact
 short_description: Downloads an Artifact from a Maven Repository
@@ -22,7 +22,7 @@ description:
 author: "Chris Schmidt (@chrisisbeef)"
 requirements:
     - lxml
-    - boto if using a S3 repository (s3://...)
+    - boto if using a S3 repository (V(s3://...))
 attributes:
     check_mode:
         support: none
@@ -32,52 +32,52 @@ options:
     group_id:
         type: str
         description:
-            - The Maven groupId coordinate
+            - The Maven groupId coordinate.
         required: true
     artifact_id:
         type: str
         description:
-            - The maven artifactId coordinate
+            - The maven artifactId coordinate.
         required: true
     version:
         type: str
         description:
-            - The maven version coordinate
+            - The maven version coordinate.
             - Mutually exclusive with O(version_by_spec).
     version_by_spec:
         type: str
         description:
             - The maven dependency version ranges.
             - See supported version ranges on U(https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution)
-            - The range type "(,1.0],[1.2,)" and "(,1.1),(1.1,)" is not supported.
+            - The range type V((,1.0],[1.2,\)) and V((,1.1\),(1.1,\)) is not supported.
             - Mutually exclusive with O(version).
         version_added: '0.2.0'
     classifier:
         type: str
         description:
-            - The maven classifier coordinate
+            - The maven classifier coordinate.
         default: ''
     extension:
         type: str
         description:
-            - The maven type/extension coordinate
+            - The maven type/extension coordinate.
         default: jar
     repository_url:
         type: str
         description:
             - The URL of the Maven Repository to download from.
-            - Use s3://... if the repository is hosted on Amazon S3, added in version 2.2.
+            - Use V(s3://...) if the repository is hosted on Amazon S3.
-            - Use file://... if the repository is local, added in version 2.6
+            - Use V(file://...) if the repository is local.
         default: https://repo1.maven.org/maven2
     username:
         type: str
         description:
-            - The username to authenticate as to the Maven Repository. Use AWS secret key of the repository is hosted on S3
+            - The username to authenticate as to the Maven Repository. Use AWS secret key of the repository is hosted on S3.
         aliases: [ "aws_secret_key" ]
     password:
         type: str
         description:
-            - The password to authenticate with to the Maven Repository. Use AWS secret access key of the repository is hosted on S3
+            - The password to authenticate with to the Maven Repository. Use AWS secret access key of the repository is hosted on S3.
         aliases: [ "aws_secret_access_key" ]
     headers:
         description:
@@ -95,19 +95,19 @@ options:
     dest:
         type: path
         description:
-            - The path where the artifact should be written to
+            - The path where the artifact should be written to.
-            - If file mode or ownerships are specified and destination path already exists, they affect the downloaded file
+            - If file mode or ownerships are specified and destination path already exists, they affect the downloaded file.
         required: true
     state:
         type: str
         description:
-            - The desired state of the artifact
+            - The desired state of the artifact.
         default: present
         choices: [present,absent]
     timeout:
         type: int
         description:
-            - Specifies a timeout in seconds for the connection attempt
+            - Specifies a timeout in seconds for the connection attempt.
         default: 10
     validate_certs:
         description:

plugins/modules/nagios.py

@@ -39,8 +39,6 @@ options:
   action:
     description:
       - Action to take.
-      - servicegroup options were added in 2.0.
-      - delete_downtime options were added in 2.2.
       - The V(acknowledge) and V(forced_check) actions were added in community.general 1.2.0.
     required: true
     choices: [ "downtime", "delete_downtime", "enable_alerts", "disable_alerts", "silence", "unsilence",

plugins/modules/pkgng.py

@@ -127,7 +127,6 @@ EXAMPLES = '''
       - bar
     state: absent
 
-# "latest" support added in 2.7
 - name: Upgrade package baz
   community.general.pkgng:
     name: baz