panics and safety documentations added

Author: orxfun

src/common_traits/from_depth_first_iter.rs

@@ -219,6 +219,13 @@ where
                 0 => {
                     let tree = Tree::new_with_root(root);
 
+                    // # SAFETY:
+                    // `push_dfs_under_root` panics if iter is empty. Therefore,
+                    //
+                    // * We first check if lower-bound(len) > 0, this allows us to directly use the iter
+                    //  which is faster.
+                    // * Otherwise, we use a peekable iterator to make sure that the iterator has at least
+                    //   one element.
                     let (lb_len, _) = iter.size_hint();
 
                     match lb_len > 0 {
@@ -238,6 +245,9 @@ where
     }
 }
 
+/// # Panics
+///
+/// Panics if the `iter` is an empty iterator. It must contain at least one child node.
 fn push_dfs_under_root<I, V, M, P>(
     mut tree: Tree<V, M, P>,
     iter: I,

src/node_mut.rs

@@ -3264,6 +3264,10 @@ where
     /// greater than one.
     /// The method returns the (depth, succeeding_depth) pair as the error when this error
     /// is observed.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the `subtree` is an empty iterator. It must contain at least one child node.
     #[allow(clippy::unwrap_in_result)]
     pub(crate) fn try_append_subtree_as_child(
         &mut self,