Add a note about counting leaves in a tree.

Author: hyanwong

docs/python-api.md

@@ -507,6 +507,14 @@ Descendant nodes
       Tree.num_samples
       Tree.num_tracked_samples
 
+Note that :meth:Tree.num_samples provides an efficient way to count samples under a node.
+However, samples and leaves are not always equivalent: some samples may be internal nodes,
+some leaves may not be samples (in unsimplified tree sequences), and the same node can be
+a leaf in one tree but internal in another. While `tree.num_samples` often equals the leaf
+count (particularly in simplified tree sequences without internal samples), a strict leaf
+count requires tree traversal, e.g. via `num_leaves = len(list(tree.leaves()))`.
+
+
 Multiple nodes
     .. autosummary::
       Tree.is_descendant