doc: fix warnings from "cargo doc"

Author: molpopgen

src/edge_table.rs

@@ -71,7 +71,7 @@ impl<'a> Iterator for EdgeTableIterator<'a> {
 /// An immutable view of an edge table.
 ///
 /// These are not created directly.
-/// Instead, use [`TableCollection::edges`](crate::TableCollection::edges)
+/// Instead, use [`TableAccess::edges`](crate::TableAccess::edges)
 /// to get a reference to an existing edge table;
 pub struct EdgeTable<'a> {
     table_: &'a ll_bindings::tsk_edge_table_t,

src/individual_table.rs

@@ -44,7 +44,7 @@ impl PartialEq for IndividualTableRow {
 /// An immutable view of a individual table.
 ///
 /// These are not created directly.
-/// Instead, use [`TableCollection::individuals`](crate::TableCollection::individuals)
+/// Instead, use [`TableAccess::individuals`](crate::TableAccess::individuals)
 /// to get a reference to an existing node table;
 pub struct IndividualTable<'a> {
     table_: &'a ll_bindings::tsk_individual_table_t,

src/lib.rs

@@ -440,15 +440,15 @@ pub use traits::TskitTypeAccess;
 pub use trees::{NodeTraversalOrder, Tree, TreeSequence};
 
 // Optional features
-#[cfg(feature = "provenance")]
+#[cfg(any(feature = "provenance", doc))]
 pub mod provenance;
 
+#[cfg(any(feature = "provenance", doc))]
 /// A provenance ID
 ///
 /// This is an integer referring to a row of a [``provenance::ProvenanceTable``].
 ///
 /// The features for this type follow the same pattern as for [``NodeId``]
-#[cfg(feature = "provenance")]
 #[repr(transparent)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, std::hash::Hash)]
 pub struct ProvenanceId(tsk_id_t);

src/migration_table.rs

@@ -80,7 +80,7 @@ impl<'a> Iterator for MigrationTableIterator<'a> {
 /// An immutable view of a migration table.
 ///
 /// These are not created directly.
-/// Instead, use [`TableCollection::migrations`](crate::TableCollection::migrations)
+/// Instead, use [`TableAccess::migrations`](crate::TableAccess::migrations)
 /// to get a reference to an existing node table;
 pub struct MigrationTable<'a> {
     table_: &'a ll_bindings::tsk_migration_table_t,

src/mutation_table.rs

@@ -75,7 +75,7 @@ impl<'a> Iterator for MutationTableIterator<'a> {
 /// An immutable view of site table.
 ///
 /// These are not created directly.
-/// Instead, use [`TableCollection::mutations`](crate::TableCollection::mutations)
+/// Instead, use [`TableAccess::mutations`](crate::TableAccess::mutations)
 /// to get a reference to an existing mutation table;
 pub struct MutationTable<'a> {
     table_: &'a ll_bindings::tsk_mutation_table_t,

src/node_table.rs

@@ -72,7 +72,7 @@ impl<'a> Iterator for NodeTableIterator<'a> {
 /// An immtable view of a node table.
 ///
 /// These are not created directly.
-/// Instead, use [`TableCollection::nodes`](crate::TableCollection::nodes)
+/// Instead, use [`TableAccess::nodes`](crate::TableAccess::nodes)
 /// to get a reference to an existing node table;
 pub struct NodeTable<'a> {
     table_: &'a ll_bindings::tsk_node_table_t,

src/population_table.rs

@@ -62,7 +62,7 @@ impl<'a> Iterator for PopulationTableIterator<'a> {
 /// An immutable view of site table.
 ///
 /// These are not created directly.
-/// Instead, use [`TableCollection::populations`](crate::TableCollection::populations)
+/// Instead, use [`TableAccess::populations`](crate::TableAccess::populations)
 /// to get a reference to an existing population table;
 pub struct PopulationTable<'a> {
     table_: &'a ll_bindings::tsk_population_table_t,

src/provenance.rs

@@ -4,11 +4,9 @@
 //! the following:
 //!
 //! * [`crate::TableCollection::add_provenance`]
-//! * [`crate::TableCollection::provenances`]
-//! * [`crate::TableCollection::provenances_iter`]
+//! * [`crate::TableAccess::provenances`]
+//! * [`crate::TableAccess::provenances_iter`]
 //! * [`crate::TreeSequence::add_provenance`]
-//! * [`crate::TreeSequence::provenances`]
-//! * [`crate::TreeSequence::provenances_iter`]
 //! * [`ProvenanceTable`].
 //! * [`ProvenanceTableRow`], which is the value type returned by
 //!   [`ProvenanceTable::iter`].
@@ -87,9 +85,8 @@ impl<'a> Iterator for ProvenanceTableIterator<'a> {
 /// An immutable view of a provenance table.
 ///
 /// These are not created directly.
-/// Instead, use [`crate::TableCollection::provenances`]
-/// or [`crate::TreeSequence::provenances`]
-/// to get a reference to an existing node table;
+/// Instead, use [`crate::TableAccess::provenances`]
+/// to get a reference to an existing provenance table;
 ///
 /// # Notes
 ///

src/site_table.rs

@@ -67,7 +67,7 @@ impl<'a> Iterator for SiteTableIterator<'a> {
 /// An immutable view of site table.
 ///
 /// These are not created directly.
-/// Instead, use [`TableCollection::sites`](crate::TableCollection::sites)
+/// Instead, use [`TableAccess::sites`](crate::TableAccess::sites)
 /// to get a reference to an existing site table;
 pub struct SiteTable<'a> {
     table_: &'a ll_bindings::tsk_site_table_t,

src/table_collection.rs

@@ -1133,7 +1133,7 @@ impl TableCollection {
         handle_tsk_return_value!(rv)
     }
 
-    #[cfg(feature = "provenance")]
+    #[cfg(any(feature = "provenance", doc))]
     /// Add provenance record with a time stamp.
     ///
     /// All implementation of this trait provided by `tskit` use
@@ -1152,6 +1152,7 @@ impl TableCollection {
     /// ```
     /// use tskit::TableAccess;
     /// let mut tables = tskit::TableCollection::new(1000.).unwrap();
+    /// # #[cfg(feature = "provenance")] {
     /// tables.add_provenance(&String::from("Some provenance")).unwrap();
     ///
     /// // Get reference to the table
@@ -1179,6 +1180,7 @@ impl TableCollection {
     /// assert_eq!(treeseq.provenances().record(0).unwrap(), "Some provenance");
     /// // We can still compare to row_0 because it is a copy of the row data:
     /// assert_eq!(treeseq.provenances().record(0).unwrap(), row_0.record);
+    /// # }
     /// ```
     pub fn add_provenance(&mut self, record: &str) -> Result<crate::ProvenanceId, TskitError> {
         let timestamp = humantime::format_rfc3339(std::time::SystemTime::now()).to_string();
@@ -1224,7 +1226,7 @@ impl TableAccess for TableCollection {
         PopulationTable::new_from_table(&(*self.inner).populations)
     }
 
-    #[cfg(feature = "provenance")]
+    #[cfg(any(feature = "provenance", doc))]
     fn provenances(&self) -> crate::provenance::ProvenanceTable {
         crate::provenance::ProvenanceTable::new_from_table(&(*self.inner).provenances)
     }

src/traits.rs

@@ -113,11 +113,11 @@ pub trait TableAccess {
         Box::new(make_table_iterator::<IndividualTable>(self.individuals()))
     }
 
-    #[cfg(feature = "provenance")]
+    #[cfg(any(feature = "provenance", doc))]
     /// Get reference to the [``ProvenanceTable``](crate::provenance::ProvenanceTable)
     fn provenances(&self) -> crate::provenance::ProvenanceTable;
 
-    #[cfg(feature = "provenance")]
+    #[cfg(any(feature = "provenance", doc))]
     /// Return an iterator over provenances
     fn provenances_iter(
         &self,

src/trees.rs

@@ -1226,7 +1226,7 @@ impl TreeSequence {
         )
     }
 
-    #[cfg(feature = "provenance")]
+    #[cfg(any(feature = "provenance", doc))]
     /// Add provenance record with a time stamp.
     ///
     /// All implementation of this trait provided by `tskit` use
@@ -1245,6 +1245,7 @@ impl TreeSequence {
     ///
     /// let mut tables = tskit::TableCollection::new(1000.).unwrap();
     /// let mut treeseq = tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
+    /// # #[cfg(feature = "provenance")] {
     /// treeseq.add_provenance(&String::from("All your provenance r belong 2 us.")).unwrap();
     ///
     /// let prov_ref = treeseq.provenances();
@@ -1257,6 +1258,7 @@ impl TreeSequence {
     /// use core::str::FromStr;
     /// let dt_utc = humantime::Timestamp::from_str(&timestamp).unwrap();
     /// println!("utc = {}", dt_utc);
+    /// # }
     /// ```
     pub fn add_provenance(&mut self, record: &str) -> Result<crate::ProvenanceId, TskitError> {
         let timestamp = humantime::format_rfc3339(std::time::SystemTime::now()).to_string();
@@ -1310,7 +1312,7 @@ impl TableAccess for TreeSequence {
         PopulationTable::new_from_table(unsafe { &(*(*self.inner).tables).populations })
     }
 
-    #[cfg(feature = "provenance")]
+    #[cfg(any(feature = "provenance", doc))]
     fn provenances(&self) -> crate::provenance::ProvenanceTable {
         crate::provenance::ProvenanceTable::new_from_table(unsafe {
             &(*(*self.inner).tables).provenances