hierarchy: more docs and first_scoe function

src/hierarchy.rs

@@ -365,33 +365,25 @@ pub struct Hierarchy {
 
 // public implementation
 impl Hierarchy {
-    // TODO: add custom iterator that guarantees a traversal in topological order
+    /// Returns an iterator over all variables (at all levels).
     pub fn iter_vars(&self) -> std::slice::Iter<'_, Var> {
         self.vars.iter()
     }
 
+    /// Returns an iterator over all scopes (at all levels).
     pub fn iter_scopes(&self) -> std::slice::Iter<'_, Scope> {
         self.scopes.iter()
     }
 
+    /// Returns an iterator over all top-level scopes and variables.
     pub fn items(&self) -> HierarchyItemIterator {
         let start = self.scopes.first().map(|s| HierarchyItem::Scope(s));
         HierarchyItemIterator::new(&self, start)
     }
 
-    pub(crate) fn num_vars(&self) -> usize {
-        self.vars.len()
-    }
-
-    pub(crate) fn num_unique_signals(&self) -> usize {
-        self.signal_idx_to_var.len()
-    }
-
-    /// Retrieves the length of a signal identified by its id by looking up a
-    /// variable that refers to the signal.
-    pub(crate) fn get_signal_length(&self, signal_idx: SignalRef) -> Option<SignalLength> {
-        let var_id = (*self.signal_idx_to_var.get(signal_idx.index())?)?;
-        Some(self.get(var_id).length)
+    /// Returns the first scope that was declared in the underlying file.
+    pub fn first_scope(&self) -> Option<&Scope> {
+        self.scopes.first()
     }
 
     /// Returns one variable per unique signal in the order of signal handles.
@@ -423,6 +415,23 @@ impl Hierarchy {
     }
 }
 
+impl Hierarchy {
+    pub(crate) fn num_vars(&self) -> usize {
+        self.vars.len()
+    }
+
+    pub(crate) fn num_unique_signals(&self) -> usize {
+        self.signal_idx_to_var.len()
+    }
+
+    /// Retrieves the length of a signal identified by its id by looking up a
+    /// variable that refers to the signal.
+    pub(crate) fn get_signal_length(&self, signal_idx: SignalRef) -> Option<SignalLength> {
+        let var_id = (*self.signal_idx_to_var.get(signal_idx.index())?)?;
+        Some(self.get(var_id).length)
+    }
+}
+
 // private implementation
 impl Hierarchy {
     fn get_str(&self, id: HierarchyStringId) -> &str {