Bug 1609662: part 4) Move documentation of `Selection::FindInsertionPoint`. r=smaug

Differential Revision: https://phabricator.services.mozilla.com/D60128

--HG--
extra : moz-landing-system : lando

dom/base/Selection.cpp

@@ -710,21 +710,12 @@ static nsresult CompareToRangeEnd(const nsINode* aCompareNode,
   return NS_OK;
 }
 
-// Selection::FindInsertionPoint
-//
-//    Binary searches the given sorted array of ranges for the insertion point
-//    for the given node/offset. The given comparator is used, and the index
-//    where the point should appear in the array is placed in *aInsertionPoint.
-//
-//    If there is an item in the array equal to the input point, we will return
-//    the index of this item.
-
 nsresult Selection::FindInsertionPoint(
     const nsTArray<RangeData>* aElementArray, const nsINode* aPointNode,
     int32_t aPointOffset,
     nsresult (*aComparator)(const nsINode*, int32_t, const nsRange*, int32_t*),
-    int32_t* aPoint) {
-  *aPoint = 0;
+    int32_t* aInsertionPoint) {
+  *aInsertionPoint = 0;
   int32_t beginSearch = 0;
   int32_t endSearch = aElementArray->Length();  // one beyond what to check
 
@@ -749,7 +740,7 @@ nsresult Selection::FindInsertionPoint(
     } while (endSearch - beginSearch > 0);
   }
 
-  *aPoint = beginSearch;
+  *aInsertionPoint = beginSearch;
   return NS_OK;
 }
 

dom/base/Selection.h

@@ -729,12 +729,21 @@ class Selection final : public nsSupportsWeakReference,
   nsresult MaybeAddTableCellRange(nsRange* aRange, bool* aDidAddRange,
                                   int32_t* aOutIndex);
 
+  /**
+   * Binary searches the given sorted array of ranges for the insertion point
+   * for the given node/offset. The given comparator is used, and the index
+   * where the point should appear in the array is placed in *aInsertionPoint.
+
+   * If there is an item in the array equal to the input point (aPointNode,
+   * aPointOffset), we will return the index of this item.
+   */
   static nsresult FindInsertionPoint(
       const nsTArray<RangeData>* aElementArray, const nsINode* aPointNode,
       int32_t aPointOffset,
       nsresult (*aComparator)(const nsINode*, int32_t, const nsRange*,
                               int32_t*),
-      int32_t* aPoint);
+      int32_t* aInsertionPoint);
+
   bool EqualsRangeAtPoint(const nsINode* aBeginNode, int32_t aBeginOffset,
                           const nsINode* aEndNode, int32_t aEndOffset,
                           int32_t aRangeIndex) const;