doc updates

Author: molpopgen

src/tree_interface.rs

@@ -392,9 +392,10 @@ impl TreeInterface {
 
     /// Return an [`Iterator`] from the node `u` to the root of the tree.
     ///
-    /// # Errors
+    /// # Returns
     ///
-    /// [`TskitError::IndexError`] if `u` is out of range.
+    /// * `Some(iterator)` if `u` us valid
+    /// * `None` otherwise
     #[deprecated(since = "0.2.3", note = "Please use Tree::parents instead")]
     pub fn path_to_root(&self, u: NodeId) -> Option<impl Iterator<Item = NodeId> + '_> {
         self.parents(u)
@@ -403,32 +404,34 @@ impl TreeInterface {
     /// Return an [`Iterator`] from the node `u` to the root of the tree,
     /// travering all parent nodes.
     ///
-    /// # Errors
+    /// # Returns
     ///
-    /// [`TskitError::IndexError`] if `u` is out of range.
+    /// * `Some(iterator)` if `u` is valid
+    /// * `None` otherwise
     pub fn parents(&self, u: NodeId) -> Option<impl Iterator<Item = NodeId> + '_> {
         ParentsIterator::new(self, u)
     }
 
     /// Return an [`Iterator`] over the children of node `u`.
+    /// # Returns
     ///
-    /// # Errors
-    ///
-    /// [`TskitError::IndexError`] if `u` is out of range.
+    /// * `Some(iterator)` if `u` is valid
+    /// * `None` otherwise
     pub fn children(&self, u: NodeId) -> Option<impl Iterator<Item = NodeId> + '_> {
         ChildIterator::new(self, u)
     }
+
     /// Return an [`Iterator`] over the sample nodes descending from node `u`.
     ///
     /// # Note
     ///
     /// If `u` is itself a sample, then it is included in the values returned.
-    /// Returns `None` if `u` is out of range.
-    ///
-    /// # Errors
+    /// 
+    /// # Returns
     ///
-    /// [`TskitError::NotTrackingSamples`] if [`TreeFlags::SAMPLE_LISTS`] was not used
-    /// to initialize `self`.
+    /// * Some(Ok(iterator)) if [`TreeFlags::SAMPLE_LISTS`] is in [`TreeInterface::flags`]
+    /// * Some(Err(_)) if [`TreeFlags::SAMPLE_LISTS`] is not in [`TreeInterface::flags`]
+    /// * None if `u` is not valid.
     pub fn samples(
         &self,
         u: NodeId,