Repository: ansible-collections/community.general

Issue:
ldap_attrs - server_uri
<!--- 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 -->
`server_uri` support several uri/server
the documentation should explain this
For me, i can use it like this : 
`server_uri: 'ldaps://ldap1,ldaps://ldap2'`
<!--- 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 -->
server_uri ( https://docs.ansible.com/ansible/latest/collections/community/general/ldap_attrs_module.html#parameter-server_uri ) support several uri .
The documentation should informe about it :  supporting several servers backend (space or coma separated)
and also support several protocol ? ( ldapi:/// , ldap:// ldaps:// )
##### ANSIBLE VERSION
<!--- Paste verbatim output from "ansible --version" between quotes -->
```paste below
ansible 2.9.17
```



Discussion:
!component =plugins/modules/net_tools/ldap/ldap_attrs.py
cc @drybjed @jtyr @nerzhul @noles
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: notify --->
@roumano I am happy to add that to the documentation, but I got concerned about what happens when URIs like `ldap://ds.example.com:389/dc=example,dc=com` or `ldap://ds.example.com:389/dc=example,dc=com?givenName,sn,cn?sub?(uid=john.doe)` are passed. Both valid and contain commas.

The module code sends the `uri` parameter as-is to `ldap.initialize()`, and the `python-ldap` docs will only say:

> The *uri* parameter may be a comma- or whitespace-separated list of URIs containing only the schema, the host, and the port fields. Note that when using multiple URIs you cannot determine to which URI your client gets connected.

Apparently, `python-ldap` delegates that to OpenLDAP's `ldap_initialize()`, and those docs state:

       ldap_initialize()  acts  like  ldap_init(),  but  it returns an integer
       indicating either success or the  failure  reason,  and  it  allows  to
       specify  details  for  the connection in the schema portion of the URI.
       The uri parameter may be a comma- or whitespace-separated list of  URIs
       containing  only the schema, the host, and the port fields.  Apart from
       ldap, other (non-standard) recognized values of the  schema  field  are
       ldaps (LDAP over TLS), ldapi (LDAP over IPC), and cldap (connectionless
       LDAP).  If other fields are present, the behavior is undefined.

That said, your request should be taken, but it should come with a warning about the types of URI supported.


Resolving patch:
diff --git a/plugins/doc_fragments/ldap.py b/plugins/doc_fragments/ldap.py
--- a/plugins/doc_fragments/ldap.py
+++ b/plugins/doc_fragments/ldap.py
@@ -38,8 +38,10 @@ class ModuleDocFragment(object):
     version_added: 2.0.0
   server_uri:
     description:
-      - A URI to the LDAP server.
+      - The I(server_uri) parameter may be a comma- or whitespace-separated list of URIs containing only the schema, the host, and the port fields.
       - The default value lets the underlying LDAP client library look for a UNIX domain socket in its default location.
+      - Note that when using multiple URIs you cannot determine to which URI your client gets connected.
+      - For URIs containing additional fields, particularly when using commas, behavior is undefined.
     type: str
     default: ldapi:///
   start_tls:


Test patch: