docstring flailing

python/tskit/trees.py

@@ -6822,19 +6822,21 @@ def decapitate(self, time, *, flags=None, population=None, metadata=None):
 
     def extend_edges(self, max_iter=10):
         """
-        Returns a new tree sequence whose unary nodes are extended to
-        neighboring trees given the following condition: While iterating over
-        the tree sequence, in each tree, we identify connecting edges with
-        unary nodes.  If an equivalent edge segment exists in the next tree
-        without that unary node, we extend the connecting edges from the
-        previous tree into the next tree, subsequently adding that unary node
-        to the tree.  This in turn reduces the length of the edge just removed
-        from the next tree, and if its length becomes zero it is removed from
-        the edge table.
-
-        : param max_iters: (int) -- the number of iterations we analyze the
-        tree sequence to edge extend.  The process will halt if there is no
-        change in edge count over two consecutive iterations.
+        TODO: make this better
+        Returns a new tree sequence in which the span covered by ancestral nodes
+        is "extended" to regions of the genome over which their ancestry is
+        unambiguous, which occurs if the node is an intermediate in a chain
+        of ancestry that also exists in neighboring regions of the genome.
+        While iterating over the tree sequence, in each tree, we identify
+        connecting edges with unary nodes.  If an equivalent edge segment
+        exists in the next tree without that unary node, we extend the
+        connecting edges from the previous tree into the next tree,
+        subsequently adding that unary node to the tree.  This in turn reduces
+        the length of the edge just removed from the next tree, and if its
+        length becomes zero it is removed from the edge table.
+
+        :param int max_iters: The maximum number of forward-and-backward
+           iterations over the tree sequence. Defaults to 10.
 
         :return: A new tree sequence with unary nodes extended.
         :rtype: tskit.TreeSequence