improve time complexity documentation

Author: Joris-van-der-Wel

lib/SymbolTree.js

@@ -147,7 +147,7 @@ class SymbolTree {
         /**
          * Find the inclusive descendant that is last in tree order of the given object.
          *
-         * `O(n)` (worst case)
+         * `O(n)` (worst case) where n is the depth of the subtree of `object`
          *
          * @method lastInclusiveDescendant
          * @memberOf module:symbol-tree#
@@ -169,7 +169,8 @@ class SymbolTree {
          * An object A is preceding an object B if A and B are in the same tree
          * and A comes before B in tree order.
          *
-         * `O(n)` (worst case)
+         * `O(n)` (worst case) <br>
+         * `O(1)` (amortized when walking the entire tree)
          *
          * @method preceding
          * @memberOf module:symbol-tree#
@@ -202,7 +203,8 @@ class SymbolTree {
          * An object A is following an object B if A and B are in the same tree
          * and A comes after B in tree order.
          *
-         * `O(n)` (worst case)
+         * `O(n)` (worst case) where n is the amount of objects in the entire tree<br>
+         * `O(1)` (amortized when walking the entire tree)
          *
          * @method following
          * @memberOf module:symbol-tree#
@@ -247,7 +249,7 @@ class SymbolTree {
         /**
          * Append all children of the given object to an array.
          *
-         * `O(n)`
+         * `O(n)` where n is the amount of children of the given `parent`
          *
          * @method childrenToArray
          * @memberOf module:symbol-tree#
@@ -287,7 +289,7 @@ class SymbolTree {
         /**
          * Append all inclusive ancestors of the given object to an array.
          *
-         * `O(n)`
+         * `O(n)` where n is the amount of ancestors of the given `object`
          *
          * @method ancestorsToArray
          * @memberOf module:symbol-tree#
@@ -320,7 +322,7 @@ class SymbolTree {
         /**
          * Append all descendants of the given object to an array (in tree order).
          *
-         * `O(n)`
+         * `O(n)` where n is the amount of objects in the sub-tree of the given `object`
          *
          * @method treeToArray
          * @memberOf module:symbol-tree#
@@ -434,8 +436,9 @@ class SymbolTree {
         /**
          * Iterate over all descendants of the given object (in tree order).
          *
-         * `O(n)` for the entire iteration<br>
-         * `O(n)` for a single iteration (worst case)
+         * where n is the amount of objects in the sub-tree of the given `root`:
+         * `O(n)` (worst case for a single iterator)
+         * `O(n)` (amortized, when completing the iterator)<br>
          *
          * @method treeIterator
          * @memberOf module:symbol-tree#
@@ -458,8 +461,8 @@ class SymbolTree {
         /**
          * Find the index of the given object (the number of preceding siblings).
          *
-         * `O(n)`<br>
-         * `O(1)` (cached)
+         * `O(n)` where n is the amount of preceding siblings<br>
+         * `O(1)` (amortized, if the tree is not modified)
          *
          * @method index
          * @memberOf module:symbol-tree#
@@ -512,8 +515,8 @@ class SymbolTree {
         /**
          * Calculate the number of children.
          *
-         * `O(n)`<br>
-         * `O(1)` (cached)
+         * `O(n)` where n is the amount of children<br>
+         * `O(1)` (amortized, if the tree is not modified)
          *
          * @method childrenCount
          * @memberOf module:symbol-tree#
@@ -544,7 +547,10 @@ class SymbolTree {
          * The semantics are the same as compareDocumentPosition in DOM, with the exception that
          * DISCONNECTED never occurs with any other bit.
          *
-         * `O(n)` (worst case)
+         * where n and m are the amount of ancestors of `left` and `right`;
+         * where o is the amount of children of the lowest common ancestor of `left` and `right`:
+         * `O(n + m + o)` (worst case)
+         * `O(n + m) (amortized, if the tree is not modified)
          *
          * @method compareTreePosition
          * @memberOf module:symbol-tree#
@@ -599,6 +605,7 @@ class SymbolTree {
                         return TreePosition.DISCONNECTED;
                 }
 
+                // find the lowest common ancestor
                 let commonAncestorIndex = 0;
                 const ancestorsMinLength = Math.min(leftAncestors.length, rightAncestors.length);