Repository: ansible/ansible
Pull request: Document group module return values
##### SUMMARY
<!--- Your description here -->
Group module return values are missing from documentation.

Return values were determined by iterating over the combinations of `state` and `system` with existent and non-existent groups.

Output of `ansible --version`:
```
ansible 2.9.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/aschultz/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.7/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 3.7.3 (default, Apr 09 2019, 05:18:21) [GCC]
```

##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr

##### SUMMARY
<!--- Describe the change below, including rationale and design decisions -->
I used the user module as a reference for style and syntax.
Fixes #65293
<!--- 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 -->
group


Problem statement:
group module return values undocumented
<!--- Verify first that your improvement is not already reported on GitHub -->
<!--- Also test if the latest release and devel branch are affected too -->
<!--- Complete *all* sections as described, this form is processed automatically -->

##### SUMMARY
<!--- Explain the problem briefly below, add suggestions to wording or structure -->
group module return values are undocumented.
<!--- HINT: Did you know the documentation has an "Edit on GitHub" link on every page ? -->

##### ISSUE TYPE
- Documentation Report

##### COMPONENT NAME
<!--- Write the short name of the rst file, module, plugin, task or feature below, use your best guess if unsure -->
group
##### ANSIBLE VERSION
<!--- Paste verbatim output from "ansible --version" between quotes -->
```paste below
ansible 2.9.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/aschultz/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.7/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 3.7.3 (default, Apr 09 2019, 05:18:21) [GCC]
```

Hints from issue discussion:

Commit message: Document group module return values

##### SUMMARY
<!--- Your description here -->
Group module return values are missing from documentation.

Return values were determined by iterating over the combinations of `state` and `system` with existent and non-existent groups.

Output of `ansible --version`:
```
ansible 2.9.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/aschultz/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.7/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 3.7.3 (default, Apr 09 2019, 05:18:21) [GCC]
```

##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr

Patch to review:
diff --git a/lib/ansible/modules/system/group.py b/lib/ansible/modules/system/group.py
index bad3157dcfd045..a76a506bca5bfb 100644
--- a/lib/ansible/modules/system/group.py
+++ b/lib/ansible/modules/system/group.py
@@ -74,6 +74,32 @@
     state: present
 '''
 
+RETURN = r'''
+gid:
+  description: Group ID of the group.
+  returned: When C(state) is 'present'
+  type: int
+  sample: 1001
+
+name:
+  description: Group name
+  returned: always
+  type: str
+  sample: users
+
+state:
+  description: Whether the group is present or not
+  returned: always
+  type: str
+  sample: 'absent'
+
+system:
+  description: Whether the group is a system group or not
+  returned: When C(state) is 'present'
+  type: bool
+  sample: False
+'''
+
 import grp
 
 from ansible.module_utils._text import to_bytes


Code review comments:
diff_hunk: @@ -74,6 +74,32 @@
     state: present
 '''
 
+RETURN = r'''
+gid:
+  description: Group ID of the group.
+  returned: When C(state) is 'present'
+  type: int
+  sample: 1001
+
path: lib/ansible/modules/system/group.py
text: @user1:
```suggestion
```

diff_hunk: @@ -74,6 +74,32 @@
     state: present
 '''
 
+RETURN = r'''
+gid:
+  description: Group ID of the group.
+  returned: When C(state) is 'present'
+  type: int
+  sample: 1001
+
+name:
+  description: Group name
+  returned: always
+  type: str
+  sample: users
+
+state:
+  description: Whether the group is present or not
+  returned: always
+  type: str
+  sample: 'absent'
+
path: lib/ansible/modules/system/group.py
text: @user1:
```suggestion
```

diff_hunk: @@ -74,6 +74,32 @@
     state: present
 '''
 
+RETURN = r'''
+gid:
+  description: Group ID of the group.
+  returned: When C(state) is 'present'
+  type: int
+  sample: 1001
+
+name:
+  description: Group name
+  returned: always
+  type: str
+  sample: users
+
path: lib/ansible/modules/system/group.py
text: @user1:
```suggestion
```