Repository: ansible/ansible
Pull request: add return documentation for unarchive.
##### SUMMARY
<!--- Describe the change below, including rationale and design decisions -->
Fixes #67445
Adds RETURN documentation for unarchive.
<!--- HINT: Include "Fixes #nnn" if you are fixing an existing issue -->

##### ISSUE TYPE
<!--- Pick one below and delete the rest -->
- Docs Pull Request

##### COMPONENT NAME
<!--- Write the short name of the module, plugin, task or feature below -->
unarchive
##### ADDITIONAL INFORMATION
<!--- Include additional information to help people understand the change here -->
<!--- A step-by-step reproduction of the problem is helpful if there is no related issue -->

<!--- Paste verbatim command output below, e.g. before and after your change -->
```paste below

```


Problem statement:
unarchive module: missing documentation on return values
##### SUMMARY
The unarchive module is missing documentation on its return values.
Only the `list_files` option mentions it at all:
> If set to True, return the list of files that are contained in the tarball.

It does not mention how this list is returned (Spoiler: It's in the `files` key, as a list of file names).
A `RETURN` section should be added to the module documentation.
Ideally, the `EXAMPLES` section should be extended to include one or two examples that use the return values somehow.

##### ISSUE TYPE
- Documentation Report

##### COMPONENT NAME
modules/files/unarchive.py

##### ANSIBLE VERSION

```
ansible 2.9.2
  config file = None
  configured module search path = ['/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib64/python3.6/site-packages/ansible
  executable location = /usr/lib/python-exec/python3.6/ansible
  python version = 3.6.9 (default, Oct  5 2019, 11:39:46) [GCC 8.3.0]
```

##### CONFIGURATION
not relevant

##### OS / ENVIRONMENT
not relevant

##### ADDITIONAL INFORMATION
<!--- Describe how this improves the documentation, e.g. before/after situation or screenshots -->

<!--- HINT: You can paste gist.github.com links for larger files -->

Hints from issue discussion:
Files identified in the description:
* [`lib/ansible/modules/files/unarchive.py`](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/files/unarchive.py)

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
cc @pileofrogs
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: notify --->
Files identified in the description:
* [`lib/ansible/modules/unarchive.py`](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/unarchive.py)

If these files are incorrect, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->

Commit message: Apply suggestions from code review

Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>

Patch to review:
diff --git a/changelogs/fragments/72546-unarchive-returndoc.yml b/changelogs/fragments/72546-unarchive-returndoc.yml
new file mode 100644
index 00000000000000..9f4fae197f9450
--- /dev/null
+++ b/changelogs/fragments/72546-unarchive-returndoc.yml
@@ -0,0 +1,2 @@
+minor_changes:
+  - unarchive - add ``RETURN`` documentation (https://github.com/ansible/ansible/issues/67445).
diff --git a/lib/ansible/modules/unarchive.py b/lib/ansible/modules/unarchive.py
index 7ccd56a0d66f58..c5e6be125d9006 100644
--- a/lib/ansible/modules/unarchive.py
+++ b/lib/ansible/modules/unarchive.py
@@ -141,6 +141,66 @@
     - s/^xxx/yyy/
 '''
 
+RETURN = r'''
+dest:
+  description: Path to the destination directory.
+  returned: always
+  type: str
+  sample: /opt/software
+files:
+  description: List of all the files in the archive.
+  returned: When I(list_files) is True
+  type: list
+  sample: '["file1", "file2"]'
+gid:
+  description: Numerical ID of the group that owns the destination directory.
+  returned: always
+  type: int
+  sample: 1000
+group:
+  description: Name of the group that owns the destination directory.
+  returned: always
+  type: str
+  sample: "librarians"
+handler:
+  description: Archive software handler used to extract and decompress the archive.
+  returned: always
+  type: str
+  sample: "TgzArchive"
+mode:
+  description: String that represents the octal permissions of the destination directory.
+  returned: always
+  type: str
+  sample: "0755"
+owner:
+  description: Name of the user that owns the destination directory.
+  returned: always
+  type: str
+  sample: "paul"
+size:
+  description: The size of destination directory in bytes. Does not include the size of files or subdirectories contained within.
+  returned: always
+  type: int
+  sample: 36
+src:
+  description:
+    - The source archive's path.
+    - If I(src) was a remote web URL, or from the local ansible controller, this shows the temporary location where the download was stored.
+  returned: always
+  type: str
+  sample: "/home/paul/test.tar.gz"
+state:
+  description: State of the destination. Effectively always "directory".
+  returned: always
+  type: str
+  sample: "directory"
+uid:
+  description: numerical ID of the user that owns the destination directory.
+  returned: always
+  type: int
+  sample: 1000
+'''
+
 import binascii
 import codecs
 import datetime


Code review comments:
diff_hunk: @@ -141,6 +141,66 @@
     - s/^xxx/yyy/
 '''
 
+RETURN = r'''
+dest:
+  description: Path to the destination directory.
+  returned: always
+  type: str
+  sample: /opt/software
+files:
+  description: List of all the files in the archive.
+  returned: When I(list_files) is True
+  type: list
+  sample: '["file1", "file2"]'
+gid:
+  description: Numerical ID of the group that owns the destination directory.
+  returned: always
+  type: int
+  sample: 1000
+group:
+  description: Name of the group that owns the destination directory.
+  returned: always
+  type: str
+  sample: "librarians"
+handler:
+  description: Archive software handler used to extract and decompress the archive.
+  returned: always
+  type: str
+  sample: "TgzArchive"
+mode:
+  description: String that represents the octal permissions of the destination directory.
+  returned: always
+  type: str
+  sample: "0755"
+owner:
+  description: Name of the user that owns the destination directory.
+  returned: always
+  type: str
+  sample: "paul"
+size:
+  description: The size of destination directory in bytes. Does not include the size of files or subdirectories contained within.
+  returned: always
+  type: int
+  sample: 36
+src:
+  description:
+    - The source archive's path.
+    - If I(src) was a remote web URL, or from the local ansible controller, this shows the temporary location where the download was stored.
+  returned: always
+  type: str
+  sample: "/home/paul/test.tar.gz"
+state:
+  description: State of the destination. Effectively always "directory".
+  returned: always
+  type: str
+  sample: "directory"
+uid:
+  description: numerical ID of the user that owns the destination directory.
path: lib/ansible/modules/unarchive.py
text: @user1:
```suggestion
  description: Numerical ID of the user that owns the destination directory.
```