DOC-3246: Final improvements

Author: MitchC1999

modules/ROOT/examples/live-demos/comments-embedded-with-mentions/index.js

@@ -19,7 +19,7 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
         description: 'Marketing Director',
       }
     }
-  }
+  };
 
   const adminUser = userDb['johnsmith'];
   const currentUser = userDb['jennynichols'];

modules/ROOT/pages/userlookup.adoc

@@ -2,48 +2,37 @@
 :navtitle: User Lookup
 :description: TinyMCE User Lookup provides an API to identify the current user and retrieve user details via integration-defined methods.
 :keywords: userLookup, fetchUsers, user_id, user management, collaborative editing
+:apiname: User Lookup
 
-The {productname} User Lookup API enables integrations to retrieve and cache user details (such as names and avatars) and identify the current user within the editor.
+The {productname} {apiname} API allows you to retrieve and cache user details, such as names and avatars, and identify the current user within the editor.
 
-This is useful when building features that rely on user context, such as commenting, collaborative editing, or displaying user-specific information. The API provides built-in caching for efficient user data management.
+This is useful when building features that rely on user context, such as commenting, collaborative editing, or displaying user-specific information. The API provides built-in caching for efficient user data management, as well as fallback user data when none is provided.
 
-== How it works
+== Properties and Methods
 
-The User Lookup API provides two main functions:
+The {apiname} API serves two purposes, to identify the current user and to fetch user details for other users. These can be configured to suit your application through the xref:#user_id[`user_id`] and xref:#fetch_users[`fetch_users`] options respectively. 
 
-[cols="2,4",options="header"]
-|===
-|Method|Description
+The {apiname} API provides properties and methods through the `editor.userLookup` object, which is available after the editor is initialized.
 
-|`editor.userLookup.userId`|Returns the current user's ID, set via the `user_id` configuration option.
-|`editor.userLookup.fetchUsers(userIds)`|Fetches and caches user information. Returns a Promise-based lookup object.
+[cols="2,1,2",options="header"]
 |===
+|API|Type|Return Type
 
-== Basic setup
-
-For a basic setup, you only need to configure the `user_id` option:
-
-[source,js]
-----
-tinymce.init({
-  selector: '#editor',
-  user_id: 'current-user-id'
-});
-----
-
-For more advanced user data fetching, see the <<options,Options>> section below.
+|xref:#userlookup-userid[`editor.userLookup.userId`]|Property|`string`
+|xref:#userlookup-fetchusers[`editor.userLookup.fetchUsers(userIds)`]|Method|`Object<string, Promise<UserObject>>`
+|===
 
-== Understanding user lookup
+[[userlookup-userid]]
+=== `editor.userLookup.userId`
 
-The User Lookup API handles three main scenarios:
+Returns the current user's ID, set via the `user_id` configuration option. This is a string that uniquely identifies the user in the context of the editor, such as a username or an email address. If the `user_id` option is not set, it defaults to `'Anonymous'`.
 
-1. **Basic identification**: Setting a current user ID for editor context
-2. **Dynamic fetching**: Retrieving user details from backend systems  
-3. **Fallback behavior**: Auto-generating user data when no fetch function is provided
+[[userlookup-fetchusers]]
+=== `editor.userLookup.fetchUsers`
 
-== Data structure
+Fetches and caches user information for the specified user IDs. This method accepts an array of user IDs and returns an object where each key is a user ID and each value is a Promise that resolves to the user object. If a user ID is not found, the Promise will reject with an error message.
 
-=== User
+=== The `user` object
 
 The user is an `Object` that contains the following fields:
 
@@ -53,7 +42,7 @@ The user is an `Object` that contains the following fields:
 | `id`       | `string`   | required  | The unique string ID of the user.
 | `name`     | `string`   | optional  | The display name of the user. If not provided, defaults to the `id`.
 | `avatar`   | `string`   | optional  | The URL of the user's avatar image or data URI. If not provided, an auto-generated SVG using the user's initials will be used.
-| `custom`   | `Object`   | optional  | Additional metadata for the user.
+| `custom`   | `Object`   | optional  | Additional metadata for the user. This can include any custom fields relevant to your application, such as roles or permissions.
 |===
 
 .Example user object:
@@ -72,46 +61,29 @@ The user is an `Object` that contains the following fields:
 
 == Options
 
-The following configuration options affect the behavior of the User Lookup API.
+The following configuration options affect the behavior of the {apiname} API.
 
 include::partial$configuration/user_id.adoc[leveloffset=+1]
 
 include::partial$configuration/fetch_users.adoc[leveloffset=+1]
 
 == Usage Examples
 
-=== Basic Usage
+=== Basic setup
 
-Once the editor is initialized, you can access the current user ID and fetch user information:
+For a basic setup, configuring the `user_id` option allows you to identify the current user. The `fetch_users` option can be omitted, and {productname} will provide fallback user data.
 
 [source,js]
 ----
-editor.on('init', () => {
-  // Get the current user ID
-  console.log('Current user:', editor.userLookup.userId);
-  
-  // Fetch user information
-  const users = editor.userLookup.fetchUsers(['user-1', 'user-2']);
-  
-  users['user-1'].then((user) => {
-    console.log('User 1 name:', user.name);
-  });
-  
-  // Handle multiple users
-  Promise.all(Object.values(users)).then((allUsers) => {
-    allUsers.forEach((user) => {
-      console.log(`Fetched: ${user.name} (${user.id})`);
-    });
-  });
+tinymce.init({
+  selector: '#editor',
+  user_id: 'alextaylor'
 });
 ----
 
-NOTE: All lookups are cached. If a user has already been fetched, the same promise will be returned without calling `fetch_users` again.
+=== Complete setup with `fetch_users`
 
-[[complete-example]]
-=== Complete Example with User Database
-
-This example shows how to set up a complete user lookup system with a simulated backend:
+This example demonstrates how to simulate user lookup in-browser. In a production environment, the `fetch_users` function would typically make network requests to your backend API.
 
 .Example
 [source,js]
@@ -140,58 +112,58 @@ tinymce.init({
     return Promise.all(
       userIds.map(
         (userId) => new Promise(
-          (resolve) => resolve(userDb[userId] || { id: userId })
+          (resolve) => resolve(userDb[userId] || { id: userId }) // Return user data or a fallback object if not found
         )
       )
     )
   },
 });
 ----
 
-This example demonstrates how to simulate user lookup in-browser. In a production environment, the `fetch_users` function would typically make network requests to your backend API.
+NOTE: It is recommended to handle (or catch) promise rejections in the `fetch_users` function by providing fallback data. This will ensure that your application can gracefully handle cases where user data is not found or the network request fails.
 
-[[fallback-behavior]]
-=== Fallback Behavior
+=== Basic usage
 
-If no `fetch_users` function is configured, {productname} will return fallback users with auto-generated data:
-
-* `name` defaults to the user ID
-* `avatar` is an auto-generated SVG using the first letter of the name
-
-This is useful for simpler setups or prototyping:
+Once the editor is initialized, you can access the current user ID and fetch user information:
 
 [source,js]
 ----
-tinymce.init({
-  selector: '#editor',
-  user_id: 'anonymous-guest'
-});
-
 editor.on('init', () => {
-  const users = editor.userLookup.fetchUsers(['anonymous-guest']);
-  users['anonymous-guest'].then((user) => {
-    console.log('Generated fallback user:', user);
+  // Get the current user ID
+  const currentUserId = editor.userLookup.userId;
+  console.log('Current user:', currentUserId);
+  
+  // Fetch user information
+  const users = editor.userLookup.fetchUsers([ currentUserId ]);
+  
+  users[currentUserId].then((user) => {
+    console.log('Current user name:', user.name);
+  });
+  
+  // Handle multiple users
+  Promise.all(Object.values(users)).then((allUsers) => {
+    allUsers.forEach((user) => {
+      console.log(`Fetched: ${user.name} (${user.id})`);
+    });
   });
 });
 ----
 
-== Advanced Usage
-
-[[ui-integration]]
-=== UI Integration Example
+=== Advanced usage with UI example
 
 This example shows how to create a toolbar button that displays the current user's information:
+
 [source,js]
 ----
 tinymce.init({
   selector: '#editor',
-  user_id: 'current-user',
+  user_id: 'alextaylor',
   setup: (editor) => {
     editor.ui.registry.addButton('show-user', {
       text: 'Show User',
       onAction: () => {
         const currentUser = editor.userLookup.userId;
-        const users = editor.userLookup.fetchUsers([currentUser]);
+        const users = editor.userLookup.fetchUsers([ currentUser ]);
 
         users[currentUser].then((user) => {
           editor.notificationManager.open({
@@ -206,15 +178,26 @@ tinymce.init({
 });
 ----
 
-[[apis]]
-== APIs
+=== Fallback Behavior
 
-The User Lookup API provides the following methods:
+If no `fetch_users` function is configured, {productname} will return fallback users with auto-generated data:
 
-[cols="3,4,2",options="header"]
-|===
-|Method|Description|Return Type
+* `name` defaults to the user ID
+* `avatar` is an auto-generated SVG using the first letter of the name
 
-|`editor.userLookup.userId`|Gets the current user's ID, set via the `user_id` configuration option.|`string`
-|`editor.userLookup.fetchUsers(userIds)`|Fetches and caches user information for the specified user IDs. Returns an object where each key is a user ID and each value is a Promise that resolves to the user object.|`Object<string, Promise<UserObject>>`
-|===
+This is useful for simpler setups or prototyping:
+
+[source,js]
+----
+tinymce.init({
+  selector: '#editor',
+  user_id: 'alextaylor'
+});
+
+editor.on('init', () => {
+  const users = editor.userLookup.fetchUsers(['alextaylor']);
+  users['alextaylor'].then((user) => {
+    console.log('Generated fallback user:', user);
+  });
+});
+----

modules/ROOT/partials/configuration/suggestededits_access.adoc

@@ -1,7 +1,7 @@
 [[suggestededits_access]]
 == `suggestededits_access`
 
-The `suggestededits_access` option determines the level of access a user has to the {pluginname} view. This setting is crucial for controlling who can accept or reject suggestions, add feedback, or view the document in read-only mode. When used in conjunction with the `readonly` option, it allows for fine-grained control over user permissions.
+The `suggestededits_access` option determines the level of access a user has to the {pluginname} view. This setting is crucial for controlling who can accept or reject suggestions, add feedback, or view suggestions in read-only mode. The `suggestededits_access` option does not control access to the editor content, however when used in conjunction with the xref:editor-important-options#readonly[`readonly`] option it allows for fine-grained control over user permissions.
 
 When set to:
 

modules/ROOT/partials/configuration/suggestededits_content.adoc

@@ -8,7 +8,7 @@ When set to:
 * `'html'`: the editor loads content normally, and the plugin synchronises the model with the content. This simplifies the configuration of {pluginname} in an existing integration, by attaching the {pluginname} model as an additional field alongside the editor content.
 * `'model'`: the editor uses the `suggestededits_model` option to generate the initial content, ignoring any pre-existing content in the editor. With this configuration, you only need to store and provide the model, simplifying the integration of the {pluginname} plugin.
 
-NOTE: The integrator is responsible for saving the model and providing it on the next load using the `suggestededits_model` option.
+NOTE: You are responsible for saving the model and providing it on the next load using the `suggestededits_model` option.
 
 *Type:* `+String+`
 

modules/ROOT/partials/events/suggestededits-events.adoc

@@ -1,6 +1,6 @@
 The following events are provided by the xref:{plugincode}.adoc[{pluginname} plugin].
 
-[cols="1,1,2",options="header"]
+[cols="2,1,3",options="header"]
 |===
 |Name |Data |Description
 |SuggestedEditsBeginReview |N/A |The Suggested Edits view has opened.