Repository: ansible-collections/community.general

Issue:
ipa_user documentation: givenname and sn are required when account doesn't exist
### Summary

These are required
- givenname
- sn

https://docs.ansible.com/ansible/latest/collections/community/general/ipa_user_module.html#ansible-collections-community-general-ipa-user-module

### Issue Type

Documentation Report

### Component Name

ipa_user

### Ansible Version

```console (paste below)
$ ansible --version
ansible [core 2.15.2]
  config file = None
  configured module search path = ['/home/cwchristerw/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /opt/ansible/lib/python3.10/site-packages/ansible
  ansible collection location = /home/cwchristerw/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/local/bin/ansible
  python version = 3.10.6 (main, May 29 2023, 11:10:38) [GCC 11.3.0] (/opt/ansible/bin/python3)
  jinja version = 3.1.2
  libyaml = True
```


### Community.general Version

```console (paste below)
$ ansible-galaxy collection list community.general
Collection        Version
----------------- -------
community.general 7.2.0
```


### Configuration

```console (paste below)
$ ansible-config dump --only-changed
-
```


### OS / Environment

Linux Mint 21.1

### Additional Information

```
fatal: [host.example.com]: FAILED! => {"changed": false, "msg": "response user_add: 'givenname' is required"}
fatal: [host.example.com]: FAILED! => {"changed": false, "msg": "response user_add: 'sn' is required"}
```

### Code of Conduct

- [X] I agree to follow the Ansible Code of Conduct


Discussion:
Files identified in the description:
* [`plugins/modules/ipa_user.py`](https://github.com/ansible-collections/community.general/blob/main/plugins/modules/ipa_user.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/devel/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
cc @Akasurde @Nosmoht @fxfitz @justchris1
[click here for bot help](https://github.com/ansible/ansibullbot/blob/devel/ISSUE_HELP.md)
<!--- boilerplate: notify --->
Hi @cwchristerw ,

Thanks for reporting! Would you be interested in working on a pull request for this?

I would suspect this is not a requirement for all states. Could you please confirm?
Yes I can make PR, and I'll check it. It's required at least when present and user isn't existing. I'll test if its required when enabled and then report back here. I'll do it ASAP, tomorrow.
Sounds to me like this should be simply documented (without a code change), since the module (via the API) already reports an error if this is missing.
Yes I agree :smile: I haven't made Docs Only PR yet :smile:
> Sounds to me like this should be simply documented (without a code change), since the module (via the API) already reports an error if this is missing.

Not sure - not checking right now - but I believe that error message is coming from the API. If we can determine with some confidence that these parameters are (always) going to be required for some of the actions, the module could perform a param validation (using `required_if`, other `required` clauses, or an actual `if` in the code) _before_ hitting the API, thus saving that HTTP  request.
@russoz they seem to be needed on creation, but not on update - so requiring them for `state=present` would be a breaking change.
Well, in that case it is indeed a simple Docs PR. :-) 

@cwchristerw please let us know if you need any further guidance, but I strongly recommend going through the https://github.com/ansible-collections/community.general/blob/main/CONTRIBUTING.md docs if you have not raised a PR for the collection before.
I haven't had time for past two weeks but I have time to do PR this weekend.

Resolving patch:
diff --git a/plugins/modules/ipa_user.py b/plugins/modules/ipa_user.py
--- a/plugins/modules/ipa_user.py
+++ b/plugins/modules/ipa_user.py
@@ -30,7 +30,9 @@
     default: 'always'
     choices: [ always, on_create ]
   givenname:
-    description: First name.
+    description:
+    - First name.
+    - If user does not exist and O(state=present), the usage of O(givenname) is required.
     type: str
   krbpasswordexpiration:
     description:
@@ -54,7 +56,9 @@
     - Will not be set for an existing user unless O(update_password=always), which is the default.
     type: str
   sn:
-    description: Surname.
+    description:
+    - Surname.
+    - If user does not exist and O(state=present), the usage of O(sn) is required.
     type: str
   sshpubkey:
     description:


Test patch: