Review fixes

src/core/spec/lang.rs

@@ -13,7 +13,7 @@ use core::{
     spec,
 };
 
-// S: an enum whose elements are the states of the CDFA for lexing a specification.
+// S: An enum whose elements are the states of the CDFA for lexing a specification.
 #[derive(PartialEq, Eq, Hash, Clone, Debug)]
 enum S {
     Start,
@@ -152,7 +152,7 @@ fn build_spec_ecdfa() -> Result<EncodedCDFA<SpecSymbol>, lex::CDFAError> {
     builder.build()
 }
 
-/// Returns the ECDFA to lex injectable specification regions, or an error if it cannot be built.
+/// Augments `builder` to lex injectable specification regions, or an error if it cannot be built.
 fn build_injectable_region(
     builder: &mut EncodedCDFABuilder<S, SpecSymbol>,
 ) -> Result<(), lex::CDFAError> {
@@ -209,7 +209,7 @@ fn build_injectable_region(
     Ok(())
 }
 
-/// Returns the ECDFA to lex ignorable specification regions, or an error if it cannot be built.
+/// Augments `builder` to lex ignorable specification regions, or an error if it cannot be built.
 fn build_ignorable_region(
     builder: &mut EncodedCDFABuilder<S, SpecSymbol>,
 ) -> Result<(), lex::CDFAError> {
@@ -241,7 +241,7 @@ fn build_ignorable_region(
     Ok(())
 }
 
-/// Returns the ECDFA to lex alphabet specification regions, or an error if it cannot be built.
+/// Augments `builder` to lex alphabet specification regions, or an error if it cannot be built.
 fn build_alphabet_region(
     builder: &mut EncodedCDFABuilder<S, SpecSymbol>,
 ) -> Result<(), lex::CDFAError> {
@@ -277,7 +277,7 @@ fn build_alphabet_region(
     Ok(())
 }
 
-/// Returns the ECDFA to lex CDFA specification regions, or an error if it cannot be built.
+/// Augments `builder` to lex CDFA specification regions, or an error if it cannot be built.
 fn build_cdfa_region(
     builder: &mut EncodedCDFABuilder<S, SpecSymbol>,
 ) -> Result<(), lex::CDFAError> {
@@ -342,7 +342,7 @@ fn build_cdfa_region(
     Ok(())
 }
 
-/// Returns the ECDFA to lex grammar specification regions, or an error if it cannot be built.
+/// Augments `builder` to lex grammar specification regions, or an error if it cannot be built.
 fn build_grammar_region(
     builder: &mut EncodedCDFABuilder<S, SpecSymbol>,
 ) -> Result<(), lex::CDFAError> {
@@ -484,7 +484,8 @@ lazy_static! {
     static ref SPEC_GRAMMAR: SimpleGrammar<SpecSymbol> = build_spec_grammar().unwrap();
 }
 
-/// Returns the grammar to parse specifications.
+/// Returns the grammar to parse specifications, or an error if there is an issue with the grammar
+/// definition.
 fn build_spec_grammar() -> Result<SimpleGrammar<SpecSymbol>, grammar::BuildError> {
     let mut builder = SimpleGrammarBuilder::new();
     builder.try_mark_start(&SpecSymbol::Spec);

src/core/spec/mod.rs

@@ -17,12 +17,12 @@ mod lang;
 mod region;
 
 lazy_static! {
-    /// The default transition matcher for CDFA specification.
+    /// The default transition matcher for CDFA specifications.
     pub static ref DEF_MATCHER: String = String::from("_");
 }
 
 /// Spec Gen Result: Stores the CDFA, grammar, and formatter produced during specification
-/// generation
+/// generation.
 type SpecGenResult<Symbol> = (
     Box<dyn CDFA<usize, Symbol>>,
     Box<dyn Grammar<Symbol>>,
@@ -35,8 +35,8 @@ pub fn parse_spec(input: &str) -> Result<Tree<SpecSymbol>, ParseError> {
     lang::parse_spec(input)
 }
 
-/// Generates a specification from a parse tree, returning the result or an error if `input` is not
-/// a valid specification.
+/// Generates a specification from a parse tree, returning the result or an error if `parse` does
+/// not represent a valid specification.
 ///
 /// # Parameters
 ///
@@ -58,10 +58,10 @@ where
 /// # Types
 ///
 /// * `MatcherErr` - indicates an error in a CDFA transition matcher definition.
-/// * `MappingErr` - indicates an error between the CDFA to grammar symbol mapping.
-/// * `CDFAErr` - indicates an internal error encountered while generating a CDFA.
-/// * `FormatterErr` - indicates an error encountered while building a formatter.
-/// * `GrammarBuildErr` - indicates an error encountered while building a grammar.
+/// * `MappingErr` - indicates an error in the CDFA to grammar symbol mapping.
+/// * `CDFAErr` - indicates an internal error encountered while building a CDFA.
+/// * `FormatterErr` - indicates an internal error encountered while building a formatter.
+/// * `GrammarBuildErr` - indicates an internal error encountered while building a grammar.
 /// * `RegionErr` - indicates and error encountered while traversing specification regions.
 #[derive(Debug)]
 pub enum GenError {
@@ -127,8 +127,8 @@ impl From<region::Error> for GenError {
 ///
 /// # Types
 ///
-/// * `LexErr` - indicates an error in the lexing stage.
-/// * `ParseErr` - indicates an error in the parsing stage.
+/// * `LexErr` - indicates a syntactic error.
+/// * `ParseErr` - indicates a semantic error.
 #[derive(Debug)]
 pub enum ParseError {
     LexErr(lex::Error),

src/core/spec/region.rs

@@ -93,7 +93,7 @@ fn type_from_node(region_node: &Tree<SpecSymbol>) -> RegionType {
     }
 }
 
-/// Error: Represents an error encountered when traversing specification regions.
+/// Error: Represents an error encountered while traversing specification regions.
 ///
 /// # Types
 ///