Apply suggestions from code review

Co-authored-by: Andrew Herron <[email protected]>
Co-authored-by: Karl Kemister-Sheppard <[email protected]>

Author: 3 people

modules/ROOT/pages/suggestededits.adoc

@@ -32,9 +32,9 @@ The {pluginname} plugin provides a dedicated `'suggestededits'` xref:custom-view
 
 The view contains a few controls to manage the review process: 
 
-* Show edits: A toggle button which hides/unhides the highlighted annotations. 
-* Complete review: Ends the review, applying the resolved changes to the document.
-* Cancel: Exits the review with no change to the document.
+* Show edits: Toggles whether suggested edits are shown. When hidden, the view shows what the document will look like if the review is completed.
+* Complete review: Ends the review, applying resolved suggestions to the document.
+* Cancel: Ignores any resolved suggestions and makes no change to the document. Feedback given on suggestions will be retained.
 
 === Document
 
@@ -50,9 +50,9 @@ Replaced content is represented as both added and removed content, and indicates
 
 Each suggested edit is listed as a card in the sidebar and color coded by the type of change, along with the user who made the suggestion, when the edit was made, and any feedback provided on that suggestion. When selected, each suggestion can be handled in the following ways:
 
-* Accept: Resolves the edit and will be applied to the document when .
-* Reject: Removes the change from the document.
-* Revert: Undoes a previously accepted or rejected change.
+* Accept: Resolves the suggestion, applying the edit to the document when the review is completed.
+* Reject: Resolves the suggestion, turning back the edit to the original state.
+* Revert: Reverts the current "Accept" or "Reject" resolution on the suggestion.
 * Provide feedback: Opens a text area for you to provide feedback on the suggestion.
 
 Any feedback will be stored in the model and displayed underneath the card details and in chronological order. This feedback thread can be used to discuss the suggestion with the author or other reviewers. The feedback author can edit or delete their own feedback.
@@ -99,13 +99,11 @@ tinymce.init({
 });
 ----
 
-This configuration will add {pluginname} to the editor toolbar, allowing users to access the plugin features. However, to fully utilize the plugin, you will need to provide additional configuration options.
-
-
+This configuration adds {pluginname} to the editor toolbar, enabling access to the plugin features. To fully utilize the plugin, additional configuration options must be provided.
 
 == Options
 
-The {pluginname} plugin requires a model to store. If the model is not provided in the editor configuration, or is `+undefined+`, the plugin will generate a new model. The model contains all the current suggested edits, so unless you are starting a new document, the current model for the document should always be provided. This model can be retrieved from the editor at any time using the xref:#get_model[`getModel` API], and should be saved externally alongside the document.
+The {pluginname} plugin requires a model for storing suggestions. If a model is not provided in the editor configuration or is set to `+undefined+`, the plugin generates a new model. This model contains all current suggested edits. To maintain continuity across sessions, the current model for the document should always be supplied unless initializing a new document. The model can be retrieved from the editor at any time using the xref:#get_model[getModel API], and should be saved externally alongside the document.
 
 Both the xref:#user_id[`+user_id+`] and xref:#fetch_users[`+fetch_users+`] options are required to configure the xref:userlookup.adoc[User Lookup API]. This API is used in the {pluginname} plugin to provide user information for each user who has made a change, allowing other users to see who made which suggestion.
 

modules/ROOT/pages/userlookup.adoc

@@ -8,7 +8,7 @@ This is useful when building features that rely on user context, such as comment
 
 == Using the User Lookup API
 
-Follow the steps below to configure and use the `userLookup` API within your integration.
+Follow the steps below to configure and use the `userLookup` API.
 
 [[step-1-set-the-current-user]]
 === 1. Set the current user ID
@@ -33,6 +33,7 @@ To simulate a backend lookup, define a local object that maps user IDs to their
 
 include::partial$configuration/fetch_users.adoc[]
 
+.Example
 [source,js]
 ----
 const userDb = {
@@ -81,6 +82,7 @@ The returned array should include objects with:
 
 Once the editor is initialized, use the API to look up multiple users:
 
+.Example
 [source,js]
 ----
 editor.on('init', () => {
@@ -103,13 +105,14 @@ NOTE: All lookups are cached. If a user has already been fetched, the same promi
 [[step-4-handle-missing-or-default-users]]
 === 4. Handle default users if `fetch_users` is not provided
 
-If no `fetch_users` function is configured, TinyMCE will return fallback users:
+If no `fetch_users` function is configured, {productname} will return fallback users:
 
 * `name` will default to the ID
 * `avatar` will be a generated SVG using the first letter of the name
 
 This is useful for simpler setups or prototyping.
 
+.Example
 [source,js]
 ----
 tinymce.init({
@@ -128,8 +131,7 @@ editor.on('init', () => {
 [[step-5-integrate-user-lookup-in-a-ui]]
 === 5. Integrate User Lookup in a UI Button (Optional)
 
-Here's how you might use the API to show the current user's name via a toolbar button.
-
+. Example: Using the API to show the current user's name via a toolbar button.
 [source,js]
 ----
 setup: (editor) => {
@@ -174,6 +176,7 @@ The `userLookup` API provides two main functions:
 
 Each returned user object from `fetchUsers()` has the following structure:
 
+.Example
 [source,js]
 ----
 {

modules/ROOT/partials/DEPRECATED/generic_8_userlookup.adoc

@@ -1 +1 @@
-IMPORTANT: This option has been deprecated in {productname} 8.0 and may be removed in a future major {productname} release. Use a combination of `user_id` and `fetch_users` instead. | `xref:apis/tinymce.editor.userlookup.adoc[UserLookup]`
+IMPORTANT: This option has been deprecated in {productname} {productmajorversion} and may be removed in a future major {productname} release. Use a combination of `user_id` and `fetch_users` instead. | `xref:apis/tinymce.editor.userlookup.adoc[UserLookup]`

modules/ROOT/partials/configuration/suggestededits_content.adoc

@@ -6,7 +6,7 @@ In a `'html'`-first approach, the editor loads content normally and the {pluginn
 
 If a model is not provided the plugin will generate a new one from the initial content of the editor.
 
-When `suggestededits_content` is set to `'model'`, the plugin bypasses the editor's content load procedures and instead uses the `suggestededits_model` option to generate initial content. This would allow an integrator to only require the model for document tracking, and treat the editor content as simply a rendering of it.
+When `suggestededits_content` is set to `'model'`, the plugin bypasses the editor's content load procedures and instead uses the `suggestededits_model` option to generate the initial content. This would allow an integrator to only require the model for document tracking, and treat the editor content as simply a rendering of it.
 
 If a model is not provided, the plugin will allow the editor to load content normally and generate a new model from there (the same way `html` works).
 

modules/ROOT/partials/configuration/tinycomments_can_delete.adoc

@@ -1,7 +1,7 @@
 [[tinycomments_can_delete]]
 == `+tinycomments_can_delete+`
 
-_Optional_: This option sets the author permissions for _deleting comment conversations_. If the `+tinycomments_can_delete+` option is not included, the current author (`+user_id+`) cannot delete comment conversations created by other authors.
+_Optional_: This option sets the author permissions for _deleting comment conversations_. If the `+tinycomments_can_delete+` option is **not included**, the current author (`+user_id+`) cannot delete comment conversations created by other authors.
 
 *Type:* `+Function+`
 

modules/ROOT/partials/configuration/tinycomments_can_delete_comment.adoc

@@ -1,7 +1,7 @@
 [[tinycomments_can_delete_comment]]
 == `+tinycomments_can_delete_comment+`
 
-_Optional_: This option sets the author permissions for _deleting comments_. If the `+tinycomments_can_delete_comment+` option is not included, the current author (`+user_id+`) **cannot** delete comments added by other authors.
+_Optional_: This option sets the author permissions for _deleting comments_. If the `+tinycomments_can_delete_comment+` option is **not included**, the current author (`+user_id+`) **cannot** delete comments added by other authors.
 
 *Type:* `+Function+`
 

modules/ROOT/partials/configuration/tinycomments_can_edit_comment.adoc

@@ -1,7 +1,7 @@
 [[tinycomments_can_edit_comment]]
 == `+tinycomments_can_edit_comment+`
 
-_Optional_: This option sets the author permissions for _editing comments_. If the `+tinycomments_can_edit_comment+` option is not included, the current author (`+user_id+`) cannot edit comments added by other authors.
+_Optional_: This option sets the author permissions for _editing comments_. If the `+tinycomments_can_edit_comment+` option is **not included**, the current author (`+user_id+`) cannot edit comments added by other authors.
 
 *Type:* `+Function+`
 

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

@@ -2,8 +2,8 @@ The following events are provided by the xref:{plugincode}.adoc[{pluginname} plu
 
 [cols="1,1,2",options="header"]
 |===
-|Name       |Data                                       |Description
-|suggestededitsBeginReview.         |N/A        |The Suggested Edits view has opened.
-|suggestededitsReviewComplete   |N/A        |A review in the Suggested Edits view has been completed. 
-|suggestededitsReviewCancelled   |N/A        |A review in the Suggested Edits view was cancelled.
+|Name |Data |Description
+|suggestededitsBeginReview |N/A |The Suggested Edits view has opened.
+|suggestededitsReviewComplete |N/A |A review in the Suggested Edits view has been completed.
+|suggestededitsReviewCancelled |N/A |A review in the Suggested Edits view was cancelled.
 |===

modules/ROOT/partials/plugin-apis/suggestededits-apis.adoc

@@ -1,11 +1,11 @@
 [cols="1,1,4",options="header"]
 |===
-|Name   |Arguments    |Description
+|Name |Arguments |Description
 
 |getModel |N/A |Returns a JSON object representing the document model and all suggested edits. 
-|setModel | `+Object+` | Set the current model of the document. 
-//|resetModel |N/A |Reset the document to its original state. 
-|hasChanges |N/A |Return a boolean value indicating whether the document contains suggested edits.  
+|setModel | `+Object+` | Sets the current model of the document. 
+//|resetModel |N/A |Resets the document to its original state. 
+|hasChanges |N/A |Returns a boolean value indicating whether the document contains any suggested edits.  
 |===
 
 .Examples
@@ -22,7 +22,9 @@ tinymce.activeEditor.plugins.suggestededits.hasChanges();
 ----
 
 [[get_model]]
-.`getModel` Example
+== `getModel`
+
+.Example
 [source,js]
 ----
 const documentId = '<YOUR_DOCUMENT_ID>'; // Replace with your document ID
@@ -72,7 +74,9 @@ tinymce.init({
 ----
 
 [[set_model]]
-.`setModel` Example
+== `setModel` 
+
+.Example
 [source,js]
 ----
 const documentIds = ['doc1', 'doc2', 'doc3']; // Example document IDs
@@ -114,7 +118,9 @@ tinymce.init({
 ----
 
 [[has_changes]]
-.`hasChanges` Example
+==`hasChanges`
+
+.Example
 [source,js]
 ----
 tinymce.init({

modules/ROOT/partials/toolbar-button-ids/suggestededits-toolbar-buttons.adoc

@@ -2,6 +2,6 @@
 |===
 |Toolbar button identifier |Description
 
-|`+suggestededits+`   |Open the Review edits view.
+|`+suggestededits+` |Opens the Review edits view.
 |`+suggestededits-label+` |Opens the Review edits view (this button uses text instead of an icon).
 |===