improve comments

Author: Alun Turner

src/components/views/rooms/wysiwyg_composer/hooks/useSuggestion.ts

@@ -83,12 +83,12 @@ export function useSuggestion(
 }
 
 /**
- * Replaces the relevant part of the editor text with the replacement mention after it is selected
- * from the autocomplete.
+ * Replaces the relevant part of the editor text with a link representing a mention after it
+ * is selected from the autocomplete.
  *
- * @param href - the href to be attached for the mention
- * @param displayName - the text to display for the mention
- * @param attributes - additional attributes to apply to the mention before adding to the editor
+ * @param href - the href that the inserted link will use
+ * @param displayName - the text content of the link
+ * @param attributes - additional attributes to add to the link, can include data-* attributes
  * @param suggestion - representation of the part of the DOM that will be replaced
  * @param setSuggestion - setter function to set the suggestion state
  * @param setText - setter function to set the content of the composer
@@ -111,12 +111,12 @@ export function processMention(
     const textBeforeReplacement = node.textContent?.slice(0, suggestion.startOffset) ?? "";
     const textAfterReplacement = node.textContent?.slice(suggestion.endOffset) ?? "";
 
-    // do this in markdown style for now
+    // TODO replace this markdown style text insertion with a pill representation
     const newText = `[${displayName}](<${href}>) `;
     const newCursorOffset = textBeforeReplacement.length + newText.length;
     const newContent = textBeforeReplacement + newText + textAfterReplacement;
 
-    // insert the new text, move the cursor, set the text state, clear the suggestion
+    // insert the new text, move the cursor, set the text state, clear the suggestion state
     node.textContent = newContent;
     document.getSelection()?.setBaseAndExtent(node, newCursorOffset, node, newCursorOffset);
     setText(newContent);
@@ -245,8 +245,8 @@ export function processSelectionChange(
         return;
     }
 
-    // here we have established that both anchor and focus nodes in the selection are
-    // the same node, so rename to `currentNode` for later use
+    // here we have established that we have a cursor and both anchor and focus nodes in the selection
+    // are the same node, so rename to `currentNode` and `currentOffset` for subsequent use
     const { anchorNode: currentNode, anchorOffset: currentOffset } = selection;
 
     // first check is that the text node is the first text node of the editor, as adding paragraphs can result
@@ -258,7 +258,7 @@ export function processSelectionChange(
 
     const mentionOrCommand = findMentionOrCommand(currentNode.textContent, currentOffset);
 
-    // if we don't have any mentionsOrCommands, return, clearing the suggeston state if it is non-null
+    // if we don't have any mentionsOrCommands, return, clearing the suggestion state
     if (mentionOrCommand === null) {
         setSuggestion(null);
         return;
@@ -284,7 +284,8 @@ export function processSelectionChange(
 
 /**
  * Given a string that represents a suggestion in the composer, return an object that represents
- * that text as a `MappedSuggestion`
+ * that text as a `MappedSuggestion`.
+ *
  * @param suggestionText - string that could be a mention of a command type suggestion
  * @returns an object representing the `MappedSuggestion` from that string
  */