[PR #5815/5e1e8d06 backport][stable-5] ldap_entry documentation is lacking examples (#6254)

ldap_entry documentation is lacking examples (#5815)

* Add changelog fragment

* Add documentation for possible values of LDAP entry attributes

* Add PR information

* Update plugins/modules/ldap_entry.py

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* remove changlog

* Update docstring

* Align ldap_attrs doc to ldap_entry module

* Update plugins/modules/ldap_attrs.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Change formulations.

---------

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 5e1e8d06ef)

Co-authored-by: Cédric Servais <cedric.servais@outlook.com>

plugins/modules/net_tools/ldap/ldap_attrs.py

@@ -57,8 +57,15 @@ options:
     required: true
     type: dict
     description:
-      - The attribute(s) and value(s) to add or remove. The complex argument format is required in order to pass
+      - The attribute(s) and value(s) to add or remove.
-        a list of strings (see examples).
+      - Each attribute value can be a string for single-valued attributes or
+        a list of strings for multi-valued attributes.
+      - If you specify values for this option in YAML, please note that you can improve
+        readability for long string values by using YAML block modifiers as seen in the
+        examples for this module.
+      - Note that when using values that YAML/ansible-core interprets as other types,
+        like C(yes), C(no) (booleans), or C(2.10) (float), make sure to quote them if
+        these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
   ordered:
     required: false
     type: bool

plugins/modules/net_tools/ldap/ldap_entry.py

@@ -36,6 +36,14 @@ options:
       - If I(state=present), attributes necessary to create an entry. Existing
         entries are never modified. To assert specific attribute values on an
         existing entry, use M(community.general.ldap_attrs) module instead.
+      - Each attribute value can be a string for single-valued attributes or
+        a list of strings for multi-valued attributes.
+      - If you specify values for this option in YAML, please note that you can improve
+        readability for long string values by using YAML block modifiers as seen in the
+        examples for this module.
+      - Note that when using values that YAML/ansible-core interprets as other types,
+        like C(yes), C(no) (booleans), or C(2.10) (float), make sure to quote them if
+        these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
     type: dict
     default: {}
   objectClass:
@@ -80,6 +88,29 @@ EXAMPLES = """
       description: An LDAP administrator
       userPassword: "{SSHA}tabyipcHzhwESzRaGA7oQ/SDoBZQOGND"
 
+- name: Set possible values for attributes elements
+  community.general.ldap_entry:
+    dn: cn=admin,dc=example,dc=com
+    objectClass:
+      - simpleSecurityObject
+      - organizationalRole
+    attributes:
+      description: An LDAP Administrator
+      roleOccupant:
+      - cn=Chocs Puddington,ou=Information Technology,dc=example,dc=com
+      - cn=Alice Stronginthebrain,ou=Information Technology,dc=example,dc=com
+      olcAccess:
+      - >-
+        {0}to attrs=userPassword,shadowLastChange
+        by self write
+        by anonymous auth
+        by dn="cn=admin,dc=example,dc=com" write
+        by * none'
+      - >-
+        {1}to dn.base="dc=example,dc=com"
+        by dn="cn=admin,dc=example,dc=com" write
+        by * read
+
 - name: Get rid of an old entry
   community.general.ldap_entry:
     dn: ou=stuff,dc=example,dc=com