doc polished

src/alerts.rs

@@ -22,14 +22,14 @@ use crate::Sodg;
 use anyhow::anyhow;
 use anyhow::Result;
 
-/// An function that is called when a problem is found in [`Sodg`].
+/// A function that is called when a problem is found in [`Sodg`].
 ///
 /// Instances of this type can be used in [`Sodg::alert_on`] method,
 /// in order to ensure runtime consistency of data inside the graph.
 pub type Alert = fn(g: &Sodg, vx: Vec<u32>) -> Vec<String>;
 
 impl Sodg {
-    /// Attach a new alert to this SODG.
+    /// Attach a new alert to this graph.
     ///
     /// For example, you don't want
     /// more than one edge to depart from any vertex:
@@ -51,8 +51,6 @@ impl Sodg {
     /// sodg.bind(0, 1, "first").unwrap();
     /// assert!(sodg.bind(0, 2, "second").is_err());
     /// ```
-    ///
-    /// If vertex `v1` already exists in the graph, an `Err` will be returned.
     pub fn alert_on(&mut self, a: Alert) {
         self.alerts.push(a);
     }

src/ctors.rs

@@ -23,7 +23,7 @@ use rstest::rstest;
 use std::collections::HashMap;
 
 impl Sodg {
-    /// Makes an empty Sodg, with no vertices and no edges.
+    /// Make an empty [`Sodg`], with no vertices and no edges.
     pub fn empty() -> Self {
         let mut g = Sodg {
             vertices: HashMap::new(),

src/edge.rs

@@ -20,7 +20,7 @@
 
 use crate::{Deserialize, Serialize};
 
-/// Edge between vertices in the graph.
+/// An edge between vertices in the graph.
 #[derive(Clone, Serialize, Deserialize, Eq, PartialOrd, PartialEq, Ord)]
 pub(crate) struct Edge {
     pub to: u32,

src/find.rs

@@ -32,23 +32,32 @@ impl Relay for DeadRelay {
 }
 
 impl DeadRelay {
-    /// Make a new one, the empty one.
+    /// Make a new [`DeadRelay`], the empty one.
     pub fn new() -> Self {
         DeadRelay {}
     }
 }
 
 impl Default for DeadRelay {
-    /// The default dead relay.
+    /// Make a new default [`DeadRelay`].
     #[allow(dead_code)]
     fn default() -> Self {
         Self::new()
     }
 }
 
 impl LambdaRelay {
-    /// Makes a new instance of `LambdaRelay` with the encapsulated
-    /// function.
+    /// Make a new instance of [`LambdaRelay`] with the encapsulated
+    /// lambda function.
+    ///
+    /// The function must accept three arguments:
+    /// 1) the ID of the vertex where the search algorithm found a problem,
+    /// 2) the head of the edge it is trying to find,
+    /// 3) the tail of the edge (may be empty). The function must
+    /// return a new locator, which the algorithm will use. If it is just
+    /// a string, it will be treated as a name of the attribute to
+    /// try instead. If it starts from `"ν"`, it is treated as an absolute
+    /// locator on the entire graph.
     #[allow(dead_code)]
     pub fn new(lambda: fn(u32, &str, &str) -> Result<String>) -> Self {
         LambdaRelay { lambda }
@@ -62,7 +71,11 @@ impl Relay for LambdaRelay {
 }
 
 impl Sodg {
-    /// Find a vertex in the Sodg by its locator using a closure to provide alternative edge names.
+    /// Find a vertex in the Sodg by its locator using a [`Relay`]
+    /// to provide alternative edge names, if the desired ones are not found.
+    ///
+    /// For example, here is how [`LambdaRelay`] may be used with a
+    /// "relaying" function:
     ///
     /// ```
     /// use sodg::Sodg;
@@ -81,7 +94,9 @@ impl Sodg {
     /// assert_eq!(1, v);
     /// ```
     ///
-    /// If target vertex is not found or `v1` is absent,
+    /// If `v1` is absent, an `Err` will be returned.
+    ///
+    /// If searching algorithm fails to find the destination,
     /// an `Err` will be returned.
     pub fn find<T: Relay>(&self, v1: u32, loc: &str, relay: &T) -> Result<u32> {
         let mut v = v1;

src/gc.rs

@@ -3,7 +3,7 @@ use anyhow::{Context, Result};
 use std::collections::VecDeque;
 
 impl Sodg {
-    /// Attempts to collect the vertex.
+    /// Attempt to collect the vertex (delete it from the graph).
     ///
     /// If there are no edges leading to it, then it is deleted and all its children are collected.
     /// Otherwise, nothing happens.

src/hex.rs

@@ -80,7 +80,7 @@ impl Hex {
         Self::from_vec(Vec::new())
     }
 
-    /// Bytes contained.
+    /// Take the bytes contained.
     ///
     /// ```
     /// use sodg::Hex;
@@ -94,7 +94,7 @@ impl Hex {
         }
     }
 
-    /// How many bytes in there.
+    /// Count, how many bytes are in there.
     ///
     /// ```
     /// use sodg::Hex;
@@ -108,7 +108,7 @@ impl Hex {
         }
     }
 
-    /// Create from slice, in appropriate mode.
+    /// Create a new [`Hex`] from slice, in appropriate mode.
     ///
     /// ```
     /// use sodg::Hex;
@@ -132,7 +132,7 @@ impl Hex {
         }
     }
 
-    /// From `Vec<u8>`.
+    /// Create a new [`Hex`] from `Vec<u8>`.
     ///
     /// ```
     /// use sodg::Hex;
@@ -147,7 +147,7 @@ impl Hex {
         }
     }
 
-    /// Make `Hex` from `String`.
+    /// Create a new [`Hex`] from `String`.
     ///
     /// ```
     /// use sodg::Hex;
@@ -158,7 +158,7 @@ impl Hex {
         Self::from_slice(d.as_bytes())
     }
 
-    /// Make hex from the bytes composing `&str`.
+    /// Create a new [`Hex`] from the bytes composing `&str`.
     ///
     /// ```
     /// use sodg::Hex;
@@ -169,7 +169,7 @@ impl Hex {
         Self::from_slice(d.as_bytes())
     }
 
-    /// It's empty and no data?
+    /// Is it empty and has no data (not a single byte)?
     ///
     /// ```
     /// use sodg::Hex;
@@ -332,7 +332,7 @@ impl Hex {
 }
 
 impl From<i64> for Hex {
-    /// Make `Hex` from `i64`.
+    /// Make a new `Hex` from `i64`.
     ///
     /// ```
     /// use sodg::Hex;
@@ -345,7 +345,7 @@ impl From<i64> for Hex {
 }
 
 impl From<f64> for Hex {
-    /// Make `Hex` from `f64`.
+    /// Make a new `Hex` from `f64`.
     ///
     /// ```
     /// use std::f64::consts::PI;
@@ -359,7 +359,7 @@ impl From<f64> for Hex {
 }
 
 impl From<bool> for Hex {
-    /// From `bool`.
+    /// Create a new [`Hex`] from `bool`.
     ///
     /// ```
     /// use sodg::Hex;
@@ -374,8 +374,9 @@ impl From<bool> for Hex {
 impl FromStr for Hex {
     type Err = anyhow::Error;
 
-    /// Create a `Hex` from a `&str` containing a hexadecimal representation of some data,
-    /// for example, `DE-AD-BE-EF-20-22`.
+    /// Create a `Hex` from a `&str` containing a hexadecimal representation of data.
+    ///
+    /// For example, this is how you make a new [`Hex`] from `"DE-AD-BE-EF-20-22"` string:
     ///
     /// ```
     /// use sodg::Hex;

src/inspect.rs

@@ -25,7 +25,7 @@ use itertools::Itertools;
 use std::collections::HashSet;
 
 impl Sodg {
-    /// Finds an object by the provided locator and prints its tree
+    /// Find an object by the provided locator and print its tree
     /// of sub-objects and edges.
     ///
     /// The function is mostly used for testing.

src/lib.rs

@@ -114,7 +114,7 @@ pub trait Relay {
 
 /// A [`Relay`] that doesn't even try to find anything, but returns an error.
 ///
-/// If you don't know what relay to use, use [`DeadRelay::new()`].
+/// If you don't know what [`Relay`] to use, use [`DeadRelay::new()`].
 pub struct DeadRelay {}
 
 /// A [`Relay`] that is made of a lambda function.
@@ -123,7 +123,7 @@ pub struct DeadRelay {}
 /// is not found, `a` is the name of the attribute, `b` is the optional locator
 /// of the attribute. The function must return a new locator where the
 /// search algorithm must continue. It can be just a name of a new attribute,
-/// or an absolute locator with dots inside.
+/// or an absolute locator (starting from `"ν"`) with dots inside.
 pub struct LambdaRelay {
     lambda: fn(u32, &str, &str) -> Result<String>,
 }

src/merge.rs

@@ -23,7 +23,7 @@ use log::debug;
 use std::collections::HashMap;
 
 impl Sodg {
-    /// Merge this new graph into itself.
+    /// Merge another graph into itself.
     pub fn merge(&mut self, g: &Sodg) {
         let mut matcher: HashMap<u32, u32> = HashMap::new();
         let mut next = self.next_id();

src/misc.rs

@@ -23,7 +23,7 @@ use crate::Sodg;
 impl Sodg {
     /// Is it empty?
     ///
-    /// Emptiness means that not a single vertex is there.
+    /// Emptiness means that not a single vertex is in the graph.
     ///
     /// ```
     /// use sodg::Sodg;

src/ops.rs

@@ -27,7 +27,9 @@ use log::trace;
 use rstest::rstest;
 
 impl Sodg {
-    /// Add a new vertex `v1` to the Sodg:
+    /// Add a new vertex `v1` to itself.
+    ///
+    /// For example:
     ///
     /// ```
     /// use sodg::Sodg;
@@ -48,11 +50,11 @@ impl Sodg {
         Ok(())
     }
 
-    /// Makes an edge `e1` from vertex `v1` to vertex `v2` and puts `a` label on it.
+    /// Make an edge `e1` from vertex `v1` to vertex `v2` and put `a` label on it.
     ///
     /// If the
     /// label is not equal to `"ρ"`, makes two backward edges from `v2` to `v1`
-    /// and label them as `"ρ"` an `"𝜎"`.
+    /// and label them as `"ρ"` an `"𝜎"`. For example:
     ///
     /// ```
     /// use sodg::Sodg;
@@ -90,6 +92,8 @@ impl Sodg {
 
     /// Set vertex data.
     ///
+    /// For example:
+    ///
     /// ```
     /// use sodg::Hex;
     /// use sodg::Sodg;
@@ -112,6 +116,8 @@ impl Sodg {
 
     /// Read vertex data, and then submit the vertex to garbage collection.
     ///
+    /// For example:
+    ///
     /// ```
     /// use sodg::Hex;
     /// use sodg::Sodg;
@@ -147,6 +153,8 @@ impl Sodg {
 
     /// Find all kids of a vertex.
     ///
+    /// For example:
+    ///
     /// ```
     /// use sodg::Sodg;
     /// let mut g = Sodg::empty();
@@ -189,6 +197,8 @@ impl Sodg {
 
     /// Find a kid of a vertex, by its edge name.
     ///
+    /// For example:
+    ///
     /// ```
     /// use sodg::Sodg;
     /// let mut g = Sodg::empty();
@@ -228,6 +238,8 @@ impl Sodg {
     /// Find a kid of a vertex, by its edge name, and return the ID of the vertex
     /// found and the locator of the edge.
     ///
+    /// For example:
+    ///
     /// ```
     /// use sodg::Sodg;
     /// let mut g = Sodg::empty();
@@ -288,7 +300,7 @@ impl Sodg {
         }
     }
 
-    /// Check whether data is there.
+    /// Check whether data is in the vertex.
     ///
     /// With this method you can check whether the data is in the vertex:
     ///

src/script.rs

@@ -27,8 +27,7 @@ use regex::Regex;
 use std::collections::HashMap;
 use std::str::FromStr;
 
-/// A wrapper of a plain text with graph-modifying
-/// instructions.
+/// A wrapper of a plain text with graph-modifying instructions.
 ///
 /// For example, you can pass the following instructions to it:
 ///
@@ -76,12 +75,12 @@ impl Script {
         }
     }
 
-    /// Make a new one, parsing a `String` with instructions.
+    /// Make a new one, parsing a [`String`] with instructions.
     pub fn from_string(s: String) -> Script {
         Script::from_str(s.as_str())
     }
 
-    /// Deploy the entire script to the SODG.
+    /// Deploy the entire script to the [`Sodg`].
     pub fn deploy_to(&mut self, g: &mut Sodg) -> Result<usize> {
         let mut pos = 0;
         for cmd in self.commands().iter() {
@@ -93,7 +92,7 @@ impl Script {
         Ok(pos)
     }
 
-    /// Get all commands
+    /// Get all commands.
     fn commands(&self) -> Vec<String> {
         lazy_static! {
             static ref STRIP_COMMENTS: Regex = Regex::new("#.*\n").unwrap();
@@ -108,7 +107,7 @@ impl Script {
             .collect()
     }
 
-    /// Deploy a single command to the sodg.
+    /// Deploy a single command to the [`Sodg`].
     fn deploy_one(&mut self, cmd: &str, g: &mut Sodg) -> Result<()> {
         lazy_static! {
             static ref LINE: Regex = Regex::new("^([A-Z]+) *\\(([^)]*)\\)$").unwrap();
@@ -161,7 +160,7 @@ impl Script {
         }
     }
 
-    /// Parses `$ν5` into `5`, and `ν23` into `23`, and `42` into `42`.
+    /// Parse `$ν5` into `5`, and `ν23` into `23`, and `42` into `42`.
     fn parse(&mut self, s: &str, g: &mut Sodg) -> Result<u32> {
         let head = s.chars().next().context("Empty identifier".to_string())?;
         if head == '$' || head == 'ν' {