doc sorting requirements (#243)

* Allow broken intradoc links in binding.rs.

* Clarify table sorting requirements in docs.

Closes #239
Closes #242

Author: molpopgen

src/lib.rs

@@ -74,6 +74,7 @@
 #![allow(non_snake_case)]
 
 #[allow(deref_nullptr)]
+#[allow(rustdoc::broken_intra_doc_links)]
 pub mod bindings;
 
 mod _macros; // Starts w/_ to be sorted at front by rustfmt!

src/table_collection.rs

@@ -626,11 +626,10 @@ impl TableCollection {
     /// The [``bookmark``](crate::types::Bookmark) can
     /// be used to affect where sorting starts from for each table.
     ///
-    /// # Note
+    /// # Details
     ///
-    /// As of `0.7.0`, this function does not sort the individual table!
-    /// See
-    /// [``topological_sort_individuals``](crate::TableCollection::topological_sort_individuals).
+    /// See [`full_sort`](crate::TableCollection::full_sort)
+    /// for more details about which tables are sorted.
     pub fn sort<O: Into<TableSortOptions>>(
         &mut self,
         start: &Bookmark,
@@ -650,10 +649,20 @@ impl TableCollection {
     /// Fully sort all tables.
     /// Implemented via a call to [``sort``](crate::TableCollection::sort).
     ///
-    /// # Note
+    /// # Details
+    ///
+    /// This function only sorts the tables that have a strict sortedness
+    /// requirement according to the `tskit` [data
+    /// model](https://tskit.dev/tskit/docs/stable/data-model.html).
+    ///
+    /// These tables are:
+    ///
+    /// * edges
+    /// * mutations
+    /// * sites
     ///
-    /// As of `0.7.0`, this function does not sort the individual table!
-    /// See
+    /// For some use cases it is desirable to have the individual table
+    /// sorted so that parents appear before offspring. See
     /// [``topological_sort_individuals``](crate::TableCollection::topological_sort_individuals).
     pub fn full_sort<O: Into<TableSortOptions>>(&mut self, options: O) -> TskReturnValue {
         let b = Bookmark::new();

src/trees.rs

@@ -975,6 +975,8 @@ impl TreeSequence {
     /// # Errors
     ///
     /// * [`TskitError`] if the tables are not indexed.
+    /// * [`TskitError`] if the tables are not properly sorted.
+    ///   See [`TableCollection::full_sort`](crate::TableCollection::full_sort).
     ///
     /// # Examples
     ///