Clarify forward-time definition of src/dest migrations

Also fixes #1157

Author: hyanwong

docs/data-model.md

@@ -298,11 +298,20 @@ required for a valid set of mutations.
 In simulations, trees can be thought of as spread across space, and it is
 helpful for inferring demographic history to record this history.
 Migrations are performed by individual ancestors, but most likely not by an
-individual whose genome is tracked as a `node` (as in a discrete-deme model they are
-unlikely to be both a migrant and a most recent common ancestor).  So,
-`tskit` records when a segment of ancestry has moved between
-populations. This table is not required, even if different nodes come from
-different populations.
+individual whose genome is tracked as a `tskit` node (as in a discrete-deme
+model they are unlikely to be both a migrant and a most recent common ancestor).
+The migrations table can be used to record when a segment of ancestry has moved
+between populations. Note that recording migrations is not compulsory: the migrations
+table can be left empty even if different nodes come from different populations.
+
+Specifically, migrations chart how edges are associated with a population.
+A migration from source population X to destination population Y
+at a given time, node, and left/right coordinate means that at the edge (or edges)
+denoted by the node and coordinates, ancestors younger than the time of
+the migration on the relevant edges can be thought of as belonging to population X
+and the older ancestors along the relevant edges can be thought of as belonging to
+population Y (at least until an intervening migration occurs). Migrations are
+recorded as follows:
 
 | Column     | Type     | Description                                            |
 | :--------- | -------- | -----------------------------------------------------: |
@@ -316,18 +325,22 @@ different populations.
 
 
 The `left` and `right` columns are floating point values defining the
-half-open segment of genome affected. The `source` and `dest` columns
-record the IDs of the respective populations. The `node` column records the
-ID of the node that was associated with the ancestry segment in question
-at the time of the migration event. The `time` column is holds floating
-point values recording the time of the event.
+half-open segment of genome affected (these need not exactly correspond to
+breakpoints between edges). The `source` column records the ID of the
+population from which, considered in forward time, migration originates. The
+`dest` column records where the migrating material ends up. The `time` column
+holds floating point values recording the time of the event, with migrations
+assumed to occur instantaneously. The `node` column records the ID of the child
+node of the migrating segment; in consequence the population ID of the `node` will
+match the `dest` ID (unless sequential migrations affect the same `node`, in which
+case it will match the `dest` value of the youngest of those migrations).
 
 The `metadata` column provides a location for client code to store
 information about each migration. See the {ref}`sec_metadata_definition` section for
 more details on how metadata columns should be used.
 
 See the {ref}`sec_migration_requirements` section for details on the properties
-required for a valid set of mutations.
+required for a valid set of migrations.
 
 
 (sec_population_table_definition)=