PR: Add comments & docstrings related to call_for_nodes

rope/base/ast.py

@@ -38,7 +38,12 @@ def parse(source, filename="<string>", *args, **kwargs):  # type: ignore
 
 
 def call_for_nodes(node, callback):
-    """If callback returns `True` the child nodes are skipped"""
+    """
+    A full preorder traversal when `bool(callback(node))` is *always* `False`.
+
+    A limited preorder traversal when `bool(callback(node)` is sometimes `True`.
+    See _ResultChecker._find_node for an example.
+    """
     result = callback(node)
     if not result:
         for child in ast.iter_child_nodes(node):

rope/refactor/similarfinder.py

@@ -153,6 +153,8 @@ def __init__(self, body, pattern, does_match):
     def find_matches(self):
         if self.matches is None:
             self.matches = []
+            # _check_nodes always returns None, so
+            # call_for_nodes traverses self.body's entire tree.
             ast.call_for_nodes(self.body, self._check_node)
         return self.matches
 

ropetest/refactor/patchedasttest.py

@@ -1488,6 +1488,21 @@ def check_region(self, text, start, end):
         self.test_case.assertEqual((start, end), node.region)
 
     def _find_node(self, text):
+        """Find the **outer-most last match** in self.ast.
+
+        For example, given the goal:
+
+            ${var1} + ${var2}
+
+        and given the text:
+
+            (a + b) + (c + (d + e))
+
+        the outermost last match would be:
+
+            (c + (d + e))
+
+        """
         goal = text
         if not isinstance(text, (tuple, list)):
             goal = [text]