From 21478e3be0bd7c6abfbb715dfed482abe642627a Mon Sep 17 00:00:00 2001
From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com>
Date: Mon, 27 Mar 2023 19:20:52 +0000
Subject: [PATCH] [PR #5815/5e1e8d06 backport][stable-5] ldap_entry
 documentation is lacking examples (#6254)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 5e1e8d06efbe870b226a8c2933da6410db55ce7c)

Co-authored-by: Cédric Servais <cedric.servais@outlook.com>
---
 plugins/modules/net_tools/ldap/ldap_attrs.py | 11 +++++--
 plugins/modules/net_tools/ldap/ldap_entry.py | 31 ++++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/plugins/modules/net_tools/ldap/ldap_attrs.py b/plugins/modules/net_tools/ldap/ldap_attrs.py
index 61ae291956..9f51b29d6f 100644
--- a/plugins/modules/net_tools/ldap/ldap_attrs.py
+++ b/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
-        a list of strings (see examples).
+      - The attribute(s) and value(s) to add or remove.
+      - 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
diff --git a/plugins/modules/net_tools/ldap/ldap_entry.py b/plugins/modules/net_tools/ldap/ldap_entry.py
index 8cacbc42c1..b918791c6a 100644
--- a/plugins/modules/net_tools/ldap/ldap_entry.py
+++ b/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