doc

Author: molpopgen

src/edge_table.rs

@@ -376,14 +376,17 @@ impl EdgeTable {
         crate::table_column::OpaqueTableColumn(self.parent_slice())
     }
 
+    /// Table column with ergonomic indexing.
     pub fn child_column(&self) -> impl crate::TableColumn<EdgeId, NodeId> + '_ {
         crate::table_column::OpaqueTableColumn(self.child_slice())
     }
 
+    /// Table column with ergonomic indexing.
     pub fn left_column(&self) -> impl crate::TableColumn<EdgeId, Position> + '_ {
         crate::table_column::OpaqueTableColumn(self.left_slice())
     }
 
+    /// Table column with ergonomic indexing.
     pub fn right_column(&self) -> impl crate::TableColumn<EdgeId, Position> + '_ {
         crate::table_column::OpaqueTableColumn(self.right_slice())
     }

src/traits.rs

@@ -144,6 +144,23 @@ impl private::NewTypeMarker for crate::ProvenanceId {}
 /// # Notes
 ///
 /// * This trait is sealed.
+///
+/// # For C programmers
+///
+/// The `C` programming language allows implicit casts between
+/// integer types.
+/// This implicit behavior allows one to index a table column
+/// using a row id type ([`crate::bindings::tsk_id_t`]) because
+/// the compiler will cast it to `size_t`.
+///
+/// `rust` does not allow implicit casts, which makes working
+/// with table columns as slices awkward.
+/// One has to manually cast the id type and the resulting code isn't
+/// nice to read.
+///
+/// This trait solves that problem by requiring that [`std::ops::Index`]
+/// by implemented for types that one would like to use as indexes
+/// in the `tskit` world.
 pub trait TableColumn<I, T>:
     std::ops::Index<I, Output = T>
     + std::ops::Index<usize, Output = T>