Add docs.

src/lib.rs

@@ -31,32 +31,43 @@ pub use crate::error::*;
 use crate::diagnostic_node::*;
 use crate::name_parsing::*;
 
+/// A graph of diagnostic statuses, following the general idea of
+/// ros aggregated diagnostics.
+///
+/// Diagnostics are stored in a tree by their namme.
+/// Their levels can be reconciled, and the individual
+/// statuses queried.
 pub struct DiagnosticGraph {
     graph: limbo_graph::Graph<DiagnosticNode>,
 }
 
 impl DiagnosticGraph {
+    /// Generate a empty graph.
     pub fn new() -> Self {
         Self {
             graph: limbo_graph::Graph::<DiagnosticNode>::new(DiagnosticNode::Root),
         }
     }
 
-    pub fn root(&self) -> limbo_graph::Key {
-        return self.graph.root_key();
-    }
-
+    /// Get the value of a specific element of the graph.
+    /// Will error if the key is not in the graph, or if the key
+    /// is the root, which doesn't have a value.
     pub fn value_of(&self, key: &limbo_graph::Key) -> Result<DiagnosticStatus> {
         let graph_value = self.graph.value_of(key)?;
         let result = graph_value.value()?;
         Ok(result.clone())
     }
 
+    /// Find all the children of key as keys.
+    /// Will error if key is not in the graph.
     pub fn children_of(&self, key: &limbo_graph::Key) -> Result<Vec<limbo_graph::Key>> {
         let result = self.graph.children_of(key)?;
         Ok(result)
     }
 
+    /// Given a key, find the child of that key that has the provided name.
+    /// The provided name must be basic (have no slashes).
+    /// Will return None if there are no children with that name.
     pub fn child_of_which_has_name(
         &self,
         parent: &limbo_graph::Key,
@@ -75,6 +86,8 @@ impl DiagnosticGraph {
         return Ok(None);
     }
 
+    /// Find the key of the item in the graph with the provided full name
+    /// (i.e. the name has slashes.)
     pub fn key_from_full_name(&self, full_name: &String) -> Result<Option<limbo_graph::Key>> {
         let name_as_vec = split_name(&full_name);
 
@@ -90,6 +103,7 @@ impl DiagnosticGraph {
         return Ok(Some(cur_base_key));
     }
 
+    /// Provide the full name for a given key. (i.e. the name will have slashes).
     pub fn full_name_from_key(&self, key: &limbo_graph::Key) -> Result<String> {
         let path_to_key = self.graph.backtrack_from_key(key)?;
         let mut full_name = String::new();
@@ -105,6 +119,7 @@ impl DiagnosticGraph {
         Ok(full_name)
     }
 
+    /// Provide the value of a status from the full name.
     pub fn value_from_name(
         &self,
         full_name: &String,
@@ -119,6 +134,9 @@ impl DiagnosticGraph {
         return Ok(Some((value, key)));
     }
 
+    /// Add a status to the graph.
+    /// The name of the status will be used to determine where in the
+    /// graph the status belongs.
     pub fn add_status(&mut self, status: DiagnosticStatus) -> Result<()> {
         // If I'm basic I just need to be added as a child of the root.
         if status.name_is_basic() {
@@ -191,6 +209,9 @@ impl DiagnosticGraph {
         Ok(())
     }
 
+    /// Add all the statuses in the provided vector.
+    /// The name of the statuses will be used to determine where in the
+    /// graph the statuses belong.
     pub fn add_status_vec(&mut self, statuses: &Vec<DiagnosticStatus>) -> Result<()> {
         for status in statuses {
             self.add_status(status.clone())?;
@@ -198,6 +219,7 @@ impl DiagnosticGraph {
         Ok(())
     }
 
+    /// Update the levels for parent nodes based on the level of their children.
     pub fn reconcile_levels(&mut self) -> Result<()> {
         let leaf_keys = self.graph.find_leaf_keys()?;