From 15d3ea123d375bde13b67f6cd82f6472b13d8ab2 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Date: Tue, 29 Jul 2025 04:46:02 +1200
Subject: [PATCH] remove common return values from docs (#10485)

* remove common return values from docs

* pacman: add note about version added of RV
---
 plugins/modules/aix_filesystem.py   | 10 ----------
 plugins/modules/aix_inittab.py      | 10 ----------
 plugins/modules/apache2_module.py   | 16 ----------------
 plugins/modules/catapult.py         |  8 --------
 plugins/modules/flatpak_remote.py   | 20 --------------------
 plugins/modules/gio_mime.py         | 12 ------------
 plugins/modules/java_cert.py        | 12 ------------
 plugins/modules/java_keystore.py    | 12 ------------
 plugins/modules/keycloak_user.py    |  9 ---------
 plugins/modules/kibana_plugin.py    |  8 --------
 plugins/modules/ldap_search.py      |  1 +
 plugins/modules/mksysb.py           |  4 ----
 plugins/modules/nsupdate.py         |  4 ----
 plugins/modules/odbc.py             |  1 +
 plugins/modules/packet_device.py    |  6 ------
 plugins/modules/packet_ip_subnet.py |  6 ------
 plugins/modules/packet_project.py   |  6 ------
 plugins/modules/packet_sshkey.py    |  5 -----
 plugins/modules/pacman.py           | 17 +----------------
 plugins/modules/rocketchat.py       |  7 -------
 plugins/modules/rpm_ostree_pkg.py   | 20 --------------------
 plugins/modules/swupd.py            | 10 ----------
 plugins/modules/syspatch.py         | 14 --------------
 plugins/modules/sysrc.py            |  7 -------
 plugins/modules/sysupgrade.py       | 15 ---------------
 plugins/modules/terraform.py        |  5 -----
 plugins/modules/timezone.py         | 14 --------------
 plugins/modules/xml.py              |  9 ---------
 28 files changed, 3 insertions(+), 265 deletions(-)

diff --git a/plugins/modules/aix_filesystem.py b/plugins/modules/aix_filesystem.py
index d952726310..92a734e8ac 100644
--- a/plugins/modules/aix_filesystem.py
+++ b/plugins/modules/aix_filesystem.py
@@ -165,16 +165,6 @@ EXAMPLES = r"""
     state: absent
 """
 
-RETURN = r"""
-changed:
-  description: Return changed for aix_filesystems actions as true or false.
-  returned: always
-  type: bool
-msg:
-  description: Return message regarding the action.
-  returned: always
-  type: str
-"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.community.general.plugins.module_utils._mount import ismount
diff --git a/plugins/modules/aix_inittab.py b/plugins/modules/aix_inittab.py
index 0c32f91e7f..ece4e95547 100644
--- a/plugins/modules/aix_inittab.py
+++ b/plugins/modules/aix_inittab.py
@@ -112,16 +112,6 @@ name:
   returned: always
   type: str
   sample: startmyservice
-msg:
-  description: Action done with the C(inittab) entry.
-  returned: changed
-  type: str
-  sample: changed inittab entry startmyservice
-changed:
-  description: Whether the C(inittab) changed or not.
-  returned: always
-  type: bool
-  sample: true
 """
 
 # Import necessary libraries
diff --git a/plugins/modules/apache2_module.py b/plugins/modules/apache2_module.py
index e02b63b2c3..99db968670 100644
--- a/plugins/modules/apache2_module.py
+++ b/plugins/modules/apache2_module.py
@@ -113,22 +113,6 @@ result:
   description: Message about action taken.
   returned: always
   type: str
-warnings:
-  description: List of warning messages.
-  returned: when needed
-  type: list
-rc:
-  description: Return code of underlying command.
-  returned: failed
-  type: int
-stdout:
-  description: The stdout of underlying command.
-  returned: failed
-  type: str
-stderr:
-  description: The stderr of underlying command.
-  returned: failed
-  type: str
 """
 
 import re
diff --git a/plugins/modules/catapult.py b/plugins/modules/catapult.py
index 5927ff24a4..448de5d13d 100644
--- a/plugins/modules/catapult.py
+++ b/plugins/modules/catapult.py
@@ -95,14 +95,6 @@ EXAMPLES = r"""
     api_secret: "{{ api_secret }}"
 """
 
-RETURN = r"""
-changed:
-  description: Whether the API accepted the message.
-  returned: always
-  type: bool
-  sample: true
-"""
-
 
 import json
 
diff --git a/plugins/modules/flatpak_remote.py b/plugins/modules/flatpak_remote.py
index bf30f6f85f..641ce930d0 100644
--- a/plugins/modules/flatpak_remote.py
+++ b/plugins/modules/flatpak_remote.py
@@ -112,26 +112,6 @@ command:
   returned: When a flatpak command has been executed
   type: str
   sample: "/usr/bin/flatpak remote-add --system flatpak-test https://dl.flathub.org/repo/flathub.flatpakrepo"
-msg:
-  description: Module error message.
-  returned: failure
-  type: str
-  sample: "Executable '/usr/local/bin/flatpak' was not found on the system."
-rc:
-  description: Return code from flatpak binary.
-  returned: When a flatpak command has been executed
-  type: int
-  sample: 0
-stderr:
-  description: Error output from flatpak binary.
-  returned: When a flatpak command has been executed
-  type: str
-  sample: "error: GPG verification enabled, but no summary found (check that the configured URL in remote config is correct)\n"
-stdout:
-  description: Output from flatpak binary.
-  returned: When a flatpak command has been executed
-  type: str
-  sample: "flathub\tFlathub\thttps://dl.flathub.org/repo/\t1\t\n"
 """
 
 from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gio_mime.py b/plugins/modules/gio_mime.py
index f81e065612..b8864ea3e3 100644
--- a/plugins/modules/gio_mime.py
+++ b/plugins/modules/gio_mime.py
@@ -61,18 +61,6 @@ handler:
   returned: success
   type: str
   sample: google-chrome.desktop
-stdout:
-  description:
-    - The output of the C(gio) command.
-  returned: success
-  type: str
-  sample: Set google-chrome.desktop as the default for x-scheme-handler/https
-stderr:
-  description:
-    - The error output of the C(gio) command.
-  returned: failure
-  type: str
-  sample: 'gio: Failed to load info for handler "never-existed.desktop"'
 version:
   description: Version of gio.
   type: str
diff --git a/plugins/modules/java_cert.py b/plugins/modules/java_cert.py
index c832a47f05..13cfea9324 100644
--- a/plugins/modules/java_cert.py
+++ b/plugins/modules/java_cert.py
@@ -197,18 +197,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-msg:
-  description: Output from stdout of keytool command after execution of given command.
-  returned: success
-  type: str
-  sample: "Module require existing keystore at keystore_path '/tmp/test/cacerts'"
-
-rc:
-  description: Keytool command execution return value.
-  returned: success
-  type: int
-  sample: "0"
-
 cmd:
   description: Executed command to get action done.
   returned: success
diff --git a/plugins/modules/java_keystore.py b/plugins/modules/java_keystore.py
index b655bbc49a..c826c9af4c 100644
--- a/plugins/modules/java_keystore.py
+++ b/plugins/modules/java_keystore.py
@@ -166,24 +166,12 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-msg:
-  description: Output from stdout of keytool/openssl command after execution of given command or an error.
-  returned: changed and failure
-  type: str
-  sample: "Unable to find the current certificate fingerprint in ..."
-
 err:
   description: Output from stderr of keytool/openssl command after error of given command.
   returned: failure
   type: str
   sample: "Keystore password is too short - must be at least 6 characters\n"
 
-rc:
-  description: Keytool/openssl command execution return value.
-  returned: changed and failure
-  type: int
-  sample: "0"
-
 cmd:
   description: Executed command to get action done.
   returned: changed and failure
diff --git a/plugins/modules/keycloak_user.py b/plugins/modules/keycloak_user.py
index 02eb226a4d..2b3c838483 100644
--- a/plugins/modules/keycloak_user.py
+++ b/plugins/modules/keycloak_user.py
@@ -332,11 +332,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-msg:
-  description: Message as to what action was taken.
-  returned: always
-  type: str
-  sample: User f18c709c-03d6-11ee-970b-c74bf2721112 created
 proposed:
   description: Representation of the proposed user.
   returned: on success
@@ -349,10 +344,6 @@ end_state:
   description: Representation of the user after module execution.
   returned: on success
   type: dict
-changed:
-  description: Return V(true) if the operation changed the user on the keycloak server, V(false) otherwise.
-  returned: always
-  type: bool
 """
 
 from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
diff --git a/plugins/modules/kibana_plugin.py b/plugins/modules/kibana_plugin.py
index 8e8ccd106d..dacfd0d824 100644
--- a/plugins/modules/kibana_plugin.py
+++ b/plugins/modules/kibana_plugin.py
@@ -109,14 +109,6 @@ timeout:
   description: The timeout for plugin download.
   returned: success
   type: str
-stdout:
-  description: The command stdout.
-  returned: success
-  type: str
-stderr:
-  description: The command stderr.
-  returned: success
-  type: str
 state:
   description: The state for the managed plugin.
   returned: success
diff --git a/plugins/modules/ldap_search.py b/plugins/modules/ldap_search.py
index 70b0088c68..47c4d8d64d 100644
--- a/plugins/modules/ldap_search.py
+++ b/plugins/modules/ldap_search.py
@@ -91,6 +91,7 @@ EXAMPLES = r"""
   register: ldap_group_gids
 """
 
+# @FIXME RV 'results' is meant to be used when 'loop:' was used with the module.
 RESULTS = r"""
 results:
   description:
diff --git a/plugins/modules/mksysb.py b/plugins/modules/mksysb.py
index 63301826de..7e188ec844 100644
--- a/plugins/modules/mksysb.py
+++ b/plugins/modules/mksysb.py
@@ -96,10 +96,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-changed:
-  description: Return changed for mksysb actions as true or false.
-  returned: always
-  type: bool
 msg:
   description: Return message regarding the action.
   returned: always
diff --git a/plugins/modules/nsupdate.py b/plugins/modules/nsupdate.py
index 45438b484e..77541c1f12 100644
--- a/plugins/modules/nsupdate.py
+++ b/plugins/modules/nsupdate.py
@@ -144,10 +144,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-changed:
-  description: If module has modified record.
-  returned: success
-  type: str
 record:
   description: DNS record.
   returned: success
diff --git a/plugins/modules/odbc.py b/plugins/modules/odbc.py
index 54c923cf1e..41b5df4f08 100644
--- a/plugins/modules/odbc.py
+++ b/plugins/modules/odbc.py
@@ -66,6 +66,7 @@ EXAMPLES = r"""
   changed_when: false
 """
 
+# @FIXME RV 'results' is meant to be used when 'loop:' was used with the module.
 RETURN = r"""
 results:
   description: List of lists of strings containing selected rows, likely empty for DDL statements.
diff --git a/plugins/modules/packet_device.py b/plugins/modules/packet_device.py
index 16766b7a91..f17db56c8c 100644
--- a/plugins/modules/packet_device.py
+++ b/plugins/modules/packet_device.py
@@ -258,12 +258,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-changed:
-  description: True if a device was altered in any way (created, modified or removed).
-  type: bool
-  sample: true
-  returned: success
-
 devices:
   description: Information about each device that was processed.
   type: list
diff --git a/plugins/modules/packet_ip_subnet.py b/plugins/modules/packet_ip_subnet.py
index ee4ebf645f..0029623a10 100644
--- a/plugins/modules/packet_ip_subnet.py
+++ b/plugins/modules/packet_ip_subnet.py
@@ -123,12 +123,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-changed:
-  description: True if an IP address assignments were altered in any way (created or removed).
-  type: bool
-  sample: true
-  returned: success
-
 device_id:
   type: str
   description: UUID of the device associated with the specified IP address.
diff --git a/plugins/modules/packet_project.py b/plugins/modules/packet_project.py
index d61c9e598b..afadec36be 100644
--- a/plugins/modules/packet_project.py
+++ b/plugins/modules/packet_project.py
@@ -110,12 +110,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-changed:
-  description: True if a project was created or removed.
-  type: bool
-  sample: true
-  returned: success
-
 name:
   description: Name of addressed project.
   type: str
diff --git a/plugins/modules/packet_sshkey.py b/plugins/modules/packet_sshkey.py
index 6761784fc5..ec76a17b4c 100644
--- a/plugins/modules/packet_sshkey.py
+++ b/plugins/modules/packet_sshkey.py
@@ -85,11 +85,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-changed:
-  description: True if a sshkey was created or removed.
-  type: bool
-  sample: true
-  returned: always
 sshkeys:
   description: Information about sshkeys that were created/removed.
   type: list
diff --git a/plugins/modules/pacman.py b/plugins/modules/pacman.py
index 0d7891c770..359cbc51d1 100644
--- a/plugins/modules/pacman.py
+++ b/plugins/modules/pacman.py
@@ -129,6 +129,7 @@ notes:
     build user with permissions to install packages could be necessary.
   - 'In the tests, while using C(yay) as the O(executable) option, the module failed to install AUR packages with the error:
     C(error: target not found: <pkg>).'
+  - The common return values `stdout` and `stderr` are returned upon success, when needed, since community.general 4.1.0.
 """
 
 RETURN = r"""
@@ -151,22 +152,6 @@ cache_updated:
   type: bool
   sample: false
   version_added: 4.6.0
-
-stdout:
-  description:
-    - Output from pacman.
-  returned: success, when needed
-  type: str
-  sample: ":: Synchronizing package databases...  core is up to date :: Starting full system upgrade..."
-  version_added: 4.1.0
-
-stderr:
-  description:
-    - Error output from pacman.
-  returned: success, when needed
-  type: str
-  sample: "warning: libtool: local (2.4.6+44+gb9b44533-14) is newer than core (2.4.6+42+gb88cebd5-15)\nwarning ..."
-  version_added: 4.1.0
 """
 
 EXAMPLES = r"""
diff --git a/plugins/modules/rocketchat.py b/plugins/modules/rocketchat.py
index 0793e9dd38..77a6ac95d7 100644
--- a/plugins/modules/rocketchat.py
+++ b/plugins/modules/rocketchat.py
@@ -159,13 +159,6 @@ EXAMPLES = r"""
   delegate_to: localhost
 """
 
-RETURN = r"""
-changed:
-  description: A flag indicating if any change was made or not.
-  returned: success
-  type: bool
-  sample: false
-"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.urls import fetch_url
diff --git a/plugins/modules/rpm_ostree_pkg.py b/plugins/modules/rpm_ostree_pkg.py
index c9f759a6fa..01462b25f1 100644
--- a/plugins/modules/rpm_ostree_pkg.py
+++ b/plugins/modules/rpm_ostree_pkg.py
@@ -82,16 +82,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-rc:
-  description: Return code of rpm-ostree command.
-  returned: always
-  type: int
-  sample: 0
-changed:
-  description: State changes.
-  returned: always
-  type: bool
-  sample: true
 action:
   description: Action performed.
   returned: always
@@ -102,16 +92,6 @@ packages:
   returned: always
   type: list
   sample: ["nfs-utils"]
-stdout:
-  description: Stdout of rpm-ostree command.
-  returned: always
-  type: str
-  sample: 'Staging deployment...done\n...'
-stderr:
-  description: Stderr of rpm-ostree command.
-  returned: always
-  type: str
-  sample: ''
 cmd:
   description: Full command used for performed action.
   returned: always
diff --git a/plugins/modules/swupd.py b/plugins/modules/swupd.py
index 5b5dbbc48a..c01904821c 100644
--- a/plugins/modules/swupd.py
+++ b/plugins/modules/swupd.py
@@ -96,16 +96,6 @@ EXAMPLES = r"""
     manifest: 12920
 """
 
-RETURN = r"""
-stdout:
-  description: C(stdout) of C(swupd).
-  returned: always
-  type: str
-stderr:
-  description: C(stderr) of C(swupd).
-  returned: always
-  type: str
-"""
 
 import os
 from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/syspatch.py b/plugins/modules/syspatch.py
index 4570a534c3..f46671fa74 100644
--- a/plugins/modules/syspatch.py
+++ b/plugins/modules/syspatch.py
@@ -59,20 +59,6 @@ EXAMPLES = r"""
 """
 
 RETURN = r"""
-rc:
-  description: The command return code (0 means success).
-  returned: always
-  type: int
-stdout:
-  description: C(syspatch) standard output.
-  returned: always
-  type: str
-  sample: "001_rip6cksum"
-stderr:
-  description: C(syspatch) standard error.
-  returned: always
-  type: str
-  sample: "syspatch: need root privileges"
 reboot_needed:
   description: Whether or not a reboot is required after an update.
   returned: always
diff --git a/plugins/modules/sysrc.py b/plugins/modules/sysrc.py
index dad379d1c0..cd7d63896b 100644
--- a/plugins/modules/sysrc.py
+++ b/plugins/modules/sysrc.py
@@ -94,13 +94,6 @@ EXAMPLES = r"""
     jail: testjail
 """
 
-RETURN = r"""
-changed:
-  description: Return changed for sysrc actions.
-  returned: always
-  type: bool
-  sample: true
-"""
 
 from ansible.module_utils.basic import AnsibleModule
 import re
diff --git a/plugins/modules/sysupgrade.py b/plugins/modules/sysupgrade.py
index 4f1d2535a5..d247e9d74c 100644
--- a/plugins/modules/sysupgrade.py
+++ b/plugins/modules/sysupgrade.py
@@ -78,21 +78,6 @@ EXAMPLES = r"""
   ignore_errors: true
 """
 
-RETURN = r"""
-rc:
-  description: The command return code (0 means success).
-  returned: always
-  type: int
-stdout:
-  description: Sysupgrade standard output.
-  returned: always
-  type: str
-stderr:
-  description: Sysupgrade standard error.
-  returned: always
-  type: str
-  sample: "sysupgrade: need root privileges"
-"""
 
 from ansible.module_utils.basic import AnsibleModule
 
diff --git a/plugins/modules/terraform.py b/plugins/modules/terraform.py
index fde826ed4f..a5adbcbe7e 100644
--- a/plugins/modules/terraform.py
+++ b/plugins/modules/terraform.py
@@ -272,11 +272,6 @@ outputs:
       type: str
       returned: always
       description: The value of the output as interpolated by Terraform.
-stdout:
-  type: str
-  description: Full C(terraform) command stdout, in case you want to display it or examine the event log.
-  returned: always
-  sample: ''
 command:
   type: str
   description: Full C(terraform) command built by this module, in case you want to re-run the command outside the module or
diff --git a/plugins/modules/timezone.py b/plugins/modules/timezone.py
index 37eb2f94a6..6e105c0bad 100644
--- a/plugins/modules/timezone.py
+++ b/plugins/modules/timezone.py
@@ -57,20 +57,6 @@ author:
   - Indrajit Raychaudhuri (@indrajitr)
 """
 
-RETURN = r"""
-diff:
-  description: The differences about the given arguments.
-  returned: success
-  type: complex
-  contains:
-    before:
-      description: The values before change.
-      type: dict
-    after:
-      description: The values after change.
-      type: dict
-"""
-
 EXAMPLES = r"""
 - name: Set timezone to Asia/Tokyo
   become: true
diff --git a/plugins/modules/xml.py b/plugins/modules/xml.py
index 49866bfeb8..3a41cd8514 100644
--- a/plugins/modules/xml.py
+++ b/plugins/modules/xml.py
@@ -342,11 +342,6 @@ actions:
       ],
       "state": "present"
     }
-backup_file:
-  description: The name of the backup file that was created.
-  type: str
-  returned: when O(backup=true)
-  sample: /path/to/file.xml.1942.2017-08-24@14:16:01~
 count:
   description: The count of xpath matches.
   type: int
@@ -356,10 +351,6 @@ matches:
   description: The xpath matches found.
   type: list
   returned: when parameter O(print_match) is set
-msg:
-  description: A message related to the performed action(s).
-  type: str
-  returned: always
 xmlstring:
   description: An XML string of the resulting output.
   type: str