union doc clarification: closes #3168

python/tests/test_tables.py

@@ -5047,6 +5047,13 @@ def test_union_empty(self):
         uni.union(empty_tables, [])
         tables.assert_equals(uni, ignore_provenance=True)
 
+    def test_contradictory_children(self):
+        # these are identical
+        ts1 = tskit.Tree.generate_comb(2, span=2).tree_sequence
+        ts2 = tskit.Tree.generate_comb(2, span=2).tree_sequence
+        with pytest.raises(_tskit.LibraryError, match="contradictory children"):
+            _ = ts1.union(ts2, node_mapping=[0, 1, -1])
+
     def test_noshared_example(self):
         ts1 = self.get_msprime_example(sample_size=3, T=2, seed=9328)
         ts2 = self.get_msprime_example(sample_size=3, T=2, seed=2125)

python/tskit/trees.py

@@ -7402,7 +7402,14 @@ def union(
            added mutation.
 
         By default, populations of newly added nodes are assumed to be new
-        populations, and added to the population table as well.
+        populations, and added to the population table as well. This can be
+        thought of as a "node-wise" union: for instance, it can not be used
+        to add new edges between two nodes already in ``self`` or new mutations
+        above nodes already in ``self``.
+
+        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.
 
         Note that this operation also sorts the resulting tables, so the
         resulting tree sequence may not be equal to ``self`` even if nothing