docstring, changelog

Author: petrelharp

python/CHANGELOG.rst

@@ -50,8 +50,9 @@
 - Add ``Mutation.inherited_state`` property which returns the inherited state
   for a single mutation. (:user:`benjeffery`, :pr:`3277`, :issue:`2631`)
 
-- Add `all_mutations` and `all_edges` parameters to `union()`, allowing disjoint unioning
-  (:user:`petrelharp`, :user:`hyanwong`, :pr:`3283`, :issue:`3181`)
+- Add ``all_mutations`` and ``all_edges`` options to ``TreeSequence.union``,
+  allowing greater flexibility in "disjoint union" situations.
+  (:user:`hyanwong`, :user:`petrelharp`, :issue:`3181`)
 
 **Bugfixes**
 
@@ -82,8 +83,8 @@
 - Prevent iterating over a ``TopologyCounter``
   (:user:`benjeffery` , :pr:`3202`, :issue:`1462`)
 
-- Fix `TreeSequence.concatenate()` to work with internal samples by using the
-  `all_mutations` and `all_edges` parameters in `union()`
+- Fix ``TreeSequence.concatenate()`` to work with internal samples by using the
+  ``all_mutations`` and ``all_edges`` parameters in ``union()``
   (:user:`hyanwong`, :pr:`3283`, :issue:`3181`)
 
 **Breaking changes**

python/tskit/trees.py

@@ -7517,6 +7517,24 @@ def union(
         nodes are in entirely new populations, then you must set up the
         population table first, and then union with ``add_populations=False``.
 
+        This method makes sense if the "shared" portions of the tree sequences
+        are equal; the option ``check_shared_equality`` performs a consistency
+        check that this is true. If this check is disabled, it is very easy to
+        produce nonsensical results via subtle inconsistencies.
+
+        The behavior above can be changed by ``all_edges`` and ``all_mutations``.
+        If ``all_edges`` is True, then all edges in ``other` are added to
+        ``self``, instead of only edges adjacent to added nodes. If
+        ``all_mutations`` is True, then similarly all mutations in ``other``
+        are added (not just those on added nodes); furthermore, all sites
+        at positions without a site already present are added to ``self``.
+        The intended use case for these options is a "disjoint" union,
+        where for instance the two tree sequences contain information about
+        disjoint segments of the genome (see :meth:`.concatenate`).
+        For some such applications it may be necessary to set
+        ``check_shared_overlap=False`` (but also easier to check for validity
+        separately).
+
         If the resulting tree sequence is invalid (for instance, a node is
         specified to have two distinct parents on the same interval),
         an error will be raised.