union doc clarification: closes #3168

[petrelharp]

Along the way I noticed another confusing thing that might happen: if you try to union two contradictory bits you get an error, so I've clarified that also. (In retrospect, not so confusing...)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.62%. Comparing base (c86884d) to head (6ece57f).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3180   +/-   ##
=======================================
  Coverage   89.62%   89.62%           
=======================================
  Files          28       28           
  Lines       31969    31969           
  Branches     5873     5873           
=======================================
  Hits        28653    28653           
  Misses       1886     1886           
  Partials     1430     1430           

Flag	Coverage Δ
c-tests	86.66% <ø> (ø)
lwt-tests	80.38% <ø> (ø)
python-c-tests	88.18% <ø> (ø)
python-tests	98.85% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
python/tskit/trees.py	98.88% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[hyanwong]

Also note a weird (to me) thing: if there is a new site with a mutation that exists at a completely new position in the "other" tree sequence, it won't be added if the node already exists in the mapping.

It's not entirely clear from the docs whether this is expected. They say that the following get added:

4. Sites which were not present in self, if the site contains a newly added mutation.

I think if a mutation is above a shared ("mapped") node (i.e. not new to self), then it doesn't count as "newly added", but perhaps the docs could be clearer.

[petrelharp]

To be clear - the situation you're talking about with mutations would also fail the check_shared_overlap check, right?

[petrelharp]

But, I think you should not be surprised by this because of

    3. Mutations whose nodes are new to ``self``.

(I guess strictly speaking reading the docs one might think that union would add the new site but not the mutation at the site, but that would be weird?) Anyhow I added a note about not being able to add new mutations to existing nodes.

[petrelharp]

This has in fact passed on re-running CircleCI:

so I'm going to merge this.