From 9f0eb3f7ad8cebb5089398d9ab88fb5ceb192c11 Mon Sep 17 00:00:00 2001 From: "Kevin R. Thornton" Date: Thu, 14 Jul 2022 10:44:09 -0700 Subject: [PATCH] doc: fix warnings from "cargo doc" --- src/edge_table.rs | 2 +- src/individual_table.rs | 2 +- src/lib.rs | 4 ++-- src/migration_table.rs | 2 +- src/mutation_table.rs | 2 +- src/node_table.rs | 2 +- src/population_table.rs | 2 +- src/provenance.rs | 11 ++++------- src/site_table.rs | 2 +- src/table_collection.rs | 6 ++++-- src/traits.rs | 4 ++-- src/trees.rs | 6 ++++-- 12 files changed, 23 insertions(+), 22 deletions(-) diff --git a/src/edge_table.rs b/src/edge_table.rs index 072246c9a..c99d06f1d 100644 --- a/src/edge_table.rs +++ b/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, diff --git a/src/individual_table.rs b/src/individual_table.rs index fd3501578..6baaafe9a 100644 --- a/src/individual_table.rs +++ b/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, diff --git a/src/lib.rs b/src/lib.rs index 8287fad8f..900eb7d51 100644 --- a/src/lib.rs +++ b/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); diff --git a/src/migration_table.rs b/src/migration_table.rs index 328da87be..ba97076ca 100644 --- a/src/migration_table.rs +++ b/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, diff --git a/src/mutation_table.rs b/src/mutation_table.rs index ba062ca9f..12f3ed7a1 100644 --- a/src/mutation_table.rs +++ b/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, diff --git a/src/node_table.rs b/src/node_table.rs index eddfca704..d81ef925a 100644 --- a/src/node_table.rs +++ b/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, diff --git a/src/population_table.rs b/src/population_table.rs index e82ad1e98..24bcdaa69 100644 --- a/src/population_table.rs +++ b/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, diff --git a/src/provenance.rs b/src/provenance.rs index 3372e0f5e..2f0eb2eed 100644 --- a/src/provenance.rs +++ b/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 /// diff --git a/src/site_table.rs b/src/site_table.rs index 42fd17618..86b587d37 100644 --- a/src/site_table.rs +++ b/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, diff --git a/src/table_collection.rs b/src/table_collection.rs index 496e5a4cb..ec34c20f1 100644 --- a/src/table_collection.rs +++ b/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 { 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) } diff --git a/src/traits.rs b/src/traits.rs index b0a5311f9..2e59dbc6c 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -113,11 +113,11 @@ pub trait TableAccess { Box::new(make_table_iterator::(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, diff --git a/src/trees.rs b/src/trees.rs index 55a5fd947..7f66e5faf 100644 --- a/src/trees.rs +++ b/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(×tamp).unwrap(); /// println!("utc = {}", dt_utc); + /// # } /// ``` pub fn add_provenance(&mut self, record: &str) -> Result { 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