DOC-3246: Improve API examples

Author: MitchC1999

modules/ROOT/partials/index-pages/premium-plugins.adoc

@@ -181,7 +181,7 @@ a|
 [.lead]
 xref:suggestededits.adoc[Suggested Edits]
 
-Review document changes by multiple users.
+Collaborate with multiple users on a document by drafting edits, providing feedback, and reviewing suggestions.
 
 a|
 [.lead]
@@ -209,4 +209,3 @@ Cloud-based file and image management for {productname}.
 //    when the number of cells in the table is even.
 a|
 |===
-

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

@@ -1,14 +1,14 @@
 [cols="1,1,4",options="header"]
 |===
 |Name |Arguments |Description
-
-|getModel |N/A |Returns a JSON object representing the document model and all 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.  
+|getModel |N/A |Returns a JSON object representing the current model of the document.
+|setModel | `+Object+` | Sets the current model of the document.
+|resetModel |N/A |Generates a model from the current content and sets it as the current model, clearing all suggestions.
+|hasChanges |N/A |Returns a boolean value indicating whether the document contains any suggested edits.
 |===
 
-.Examples
+== Examples
+
 [source,js]
 ----
 // Get the current model of the document
@@ -17,18 +17,20 @@ tinymce.activeEditor.plugins.suggestededits.getModel();
 // Set current model of the document
 tinymce.activeEditor.plugins.suggestededits.setModel(model);
 
+// Reset the model to the current content, clearing all suggestions
+tinymce.activeEditor.plugins.suggestededits.resetModel();
+
 // Check if document contains changes to be reviewed 
 tinymce.activeEditor.plugins.suggestededits.hasChanges();
 ----
 
 [[get_model]]
-== `getModel`
+== `getModel` Example
+
+This example demonstrates how to submit the current document and model to a server, to ensure they are saved synchronously. The current model is retrieved using the `getModel` API.
 
-.Example
 [source,js]
 ----
-const documentId = '<YOUR_DOCUMENT_ID>'; // Replace with your document ID
-
 tinymce.init({
   selector: 'textarea#suggestededits',  // change this value according to your HTML
   plugins: 'suggestededits',
@@ -49,7 +51,7 @@ tinymce.init({
           headers: {
             'Content-Type': 'application/json',
           },
-          body: JSON.stringify({ content, model }),
+          body: content,
         })
         .then((response) => response.json())
         .then((data) => console.log('Document saved:', data))
@@ -74,53 +76,64 @@ tinymce.init({
 ----
 
 [[set_model]]
-== `setModel` 
+== `setModel` Example
+
+This example demonstrates how to set the model and the document in the editor, after fetching them from a server. The `setModel` method sets the current model of the document and the editor content, as generated from that model.
 
-.Example
 [source,js]
 ----
-const documentIds = ['doc1', 'doc2', 'doc3']; // Example document IDs
-
 tinymce.init({
   selector: 'textarea#suggestededits',  // change this value according to your HTML
   plugins: 'suggestededits',
   toolbar: 'suggestededits',
   setup: (editor) => {
-    // Function to load a document and its model
-    function loadDocument(documentId) {
-      // Fetch and set the document content
-      fetch(`/api/documents/${documentId}`)
-        .then((response) => response.text())
-        .then((content) => {
-          editor.setContent(content);
-        })
-        .catch((error) => console.error(`Error fetching document ${documentId}:`, error));
-
+    editor.on('init', () => {
       // Fetch and set the suggested edits model
       fetch(`/api/models/${documentId}`)
         .then((response) => response.json())
         .then((model) => {
           editor.plugins.suggestededits.setModel(model);
         })
         .catch((error) => console.error(`Error fetching model for ${documentId}:`, error));
-    }
-
-    // Example: Attach to a button click event
-    document.getElementById('loadDocBtn').addEventListener('click', () => {
-      const selectedId = document.getElementById('docSelect').value;
-      loadDocument(selectedId);
     });
+  }
+});
+----
+
+[[reset_model]]
+== `resetModel` Example
 
-    // Optionally, load the first document on init
-    loadDocument(documentIds[0]);
+This example demonstrates how to reset the model to the current content of the editor, clearing all suggestions. The `resetModel` method generates a new model from the current content and sets it as the current model.
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea#suggestededits',  // change this value according to your HTML
+  plugins: 'suggestededits',
+  toolbar: 'suggestededits clearsuggestions',
+  setup: (editor) => {
+    editor.ui.registry.addButton('clearsuggestions', {
+      text: 'Clear Suggestions',
+      onAction: () => {
+        // Reset the model to the current content, clearing all suggestions
+        editor.plugins.suggestededits.resetModel();
+        
+        editor.notificationManager.open({
+          text: 'All suggestions have been cleared.',
+          type: 'info',
+          timeout: 5000,
+        });
+      }
+    });
   }
 });
 ----
 
 [[has_changes]]
-==`hasChanges`
+== `hasChanges` Example
+
+This example demonstrates how to check if there are any changes in the document that need to be reviewed before saving. The `hasChanges` method is used to determine if there are any unreviewed edits.
 
-.Example
 [source,js]
 ----
 tinymce.init({
@@ -148,20 +161,3 @@ tinymce.init({
   }
 });
 ----
-////
-.Examples
-[source,js]
-----
-// Get the current model of the document
-tinymce.activeEditor.plugins.suggestededits.getModel();
-
-// Set current model of the document 
-tinymce.activeEditor.plugins.suggestededits.setModel(model);
-
-// Reset the document model to its original state 
-tinymce.activeEditor.plugins.suggestededits.resetModel();
-
-// Check if document contains changes to be reviewed 
-tinymce.activeEditor.plugins.suggestededits.hasChanges();
-----
-////