From e36ff9023c7bc7348b5086aee15f188157c4010d Mon Sep 17 00:00:00 2001
From: Rajat Bajaj <rajat.bajaj@okta.com>
Date: Tue, 11 Feb 2025 08:51:57 +0530
Subject: [PATCH] Updated documentation

---
 docs/data-sources/user.md          |  4 ++--
 internal/auth0/user/data_source.go | 11 +++++++++--
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/data-sources/user.md b/docs/data-sources/user.md
index cce8d5d8..bfe6ab28 100644
--- a/docs/data-sources/user.md
+++ b/docs/data-sources/user.md
@@ -1,12 +1,12 @@
 ---
 page_title: "Data Source: auth0_user"
 description: |-
-  Data source to retrieve a specific Auth0 user by user_id.
+  Data source to retrieve a specific Auth0 user by user_id or by lucene query. If filtered by Lucene Query, it should include sufficient filters to retrieve a unique user.
 ---
 
 # Data Source: auth0_user
 
-Data source to retrieve a specific Auth0 user by `user_id`.
+Data source to retrieve a specific Auth0 user by `user_id` or by `lucene query`. If filtered by Lucene Query, it should include sufficient filters to retrieve a unique user.
 
 ## Example Usage
 
diff --git a/internal/auth0/user/data_source.go b/internal/auth0/user/data_source.go
index 242bbe66..528b17d8 100644
--- a/internal/auth0/user/data_source.go
+++ b/internal/auth0/user/data_source.go
@@ -15,8 +15,9 @@ import (
 func NewDataSource() *schema.Resource {
 	return &schema.Resource{
 		ReadContext: readUserForDataSource,
-		Description: "Data source to retrieve a specific Auth0 user by `user_id`.",
-		Schema:      dataSourceSchema(),
+		Description: "Data source to retrieve a specific Auth0 user by `user_id` or by `lucene query`. " +
+			"If filtered by Lucene Query, it should include sufficient filters to retrieve a unique user.",
+		Schema: dataSourceSchema(),
 	}
 }
 
@@ -97,6 +98,10 @@ func readUserForDataSource(ctx context.Context, data *schema.ResourceData, meta
 		if err != nil {
 			return diag.FromErr(err)
 		}
+
+		// The data-source retrieves the roles and permissions for a user.
+		// Hence, it is important the search bottoms out to a single user.
+		// If multiple users are retrieved via Lucene Query, we prompt the user to add further filters.
 		if users.Length == 1 {
 			user = users.Users[0]
 			data.SetId(users.Users[0].GetID())
@@ -105,6 +110,7 @@ func readUserForDataSource(ctx context.Context, data *schema.ResourceData, meta
 		}
 	}
 
+	// Populate Roles for the retrieved User.
 	var roles []*management.Role
 	var rolesPage int
 	for {
@@ -122,6 +128,7 @@ func readUserForDataSource(ctx context.Context, data *schema.ResourceData, meta
 		rolesPage++
 	}
 
+	// Populate Permissions for the retrieved User.
 	var permissions []*management.Permission
 	var permissionsPage int
 	for {