docs: various fixes in docstrings

rustemo-compiler/src/lib.rs

@@ -1,7 +1,7 @@
 //! This crate provides a Rustemo grammars compiler as a CLI command, and an API
 //! for usage from `build.rs` scripts.
 //!
-//! When this crate is installed `rustemo` command is available that can be run
+//! When this crate is installed `rcomp` command is available that can be run
 //! over Rustemo grammars to produce parsers.
 //!
 //! The entry point into API is [Settings::new] which provide a default settings
@@ -17,7 +17,7 @@
 //!
 //! # Processing grammars
 //!
-//! For a default settings there are [process_crate_dir], [process_dir] and
+//! For default settings there are [process_crate_dir], [process_dir] and
 //! [process_grammar] shortcut functions.
 //!
 //! ## Example

rustemo-compiler/src/settings.rs

@@ -15,6 +15,7 @@ pub enum ParserAlgo {
     GLR,
 }
 
+/// The lexer type used during parsing to break the input into tokens
 #[derive(Debug, Default, Clone, ArgEnum)]
 pub enum LexerType {
     /// Default lexer if the input is `str` is based on string/regex recognizers
@@ -24,6 +25,7 @@ pub enum LexerType {
     Custom,
 }
 
+/// The builder type used during parsing to construct the output
 #[derive(Debug, Default, Clone, ArgEnum)]
 pub enum BuilderType {
     /// Default builder type constructs AST using inferred node types

rustemo-compiler/src/utils.rs

@@ -3,6 +3,7 @@ pub fn type_of<T>(_: &T) -> &'static str {
     std::any::type_name::<T>()
 }
 
+/// Returns a first difference between two strings. Used by `output_cmp!` macro.
 pub fn string_difference(a: &str, b: &str) -> Option<(usize, (char, char))> {
     a.chars()
         .zip(b.chars())
@@ -57,7 +58,7 @@ macro_rules! output_cmp {
 pub use output_cmp;
 
 /// Used in tests to calculate local file path relative to the source file.
-/// Requires call to file!() as a first parameter.
+/// Requires call to `file!()` as a first parameter.
 ///
 /// # Example
 /// ```rust

rustemo/src/context.rs

@@ -2,28 +2,32 @@ use std::ops::Range;
 
 use crate::{input::Input, lexer::Token, location::Location, parser::State};
 
-/// Lexer context is used to keep the lexing state. It provides necessary
+/// Lexer/Parser context is used to keep the state. It provides necessary
 /// information to parsers and actions.
 pub trait Context<'i, I: Input + ?Sized, S: State, TK> {
     /// The current parser state.
     fn state(&self) -> S;
     fn set_state(&mut self, state: S);
 
-    /// An absolute position inthe input sequence
+    /// An absolute position in the input sequence
     ///
     /// The input must be indexable type.
     fn position(&self) -> usize;
     fn set_position(&mut self, position: usize);
 
+    /// A span in the input sequence, possibly in line-column style.
     fn location(&self) -> Location;
     fn set_location(&mut self, location: Location);
 
+    /// A span in the input sequence
     fn range(&self) -> Range<usize>;
     fn set_range(&mut self, range: Range<usize>);
 
+    /// Next token recognized in the input at the current parsing location
     fn token_ahead(&self) -> Option<&Token<'i, I, TK>>;
     fn set_token_ahead(&mut self, token: Token<'i, I, TK>);
 
+    /// A layout before the token ahead
     fn layout_ahead(&self) -> Option<&'i I>;
     fn set_layout_ahead(&mut self, layout: Option<&'i I>);
 }

rustemo/src/glr/gss.rs

@@ -129,7 +129,8 @@ impl<'i, I: Input + ?Sized, S, P, TK: Copy> GssGraph<'i, I, S, P, TK> {
     }
 }
 
-/// A node/head in the Graph Structured Stack (GSS).
+/// A node/head in the Graph Structured Stack (GSS). Implements [`Context`] for
+/// GLR parsing.
 ///
 /// Each head is related to a LR parser state and a single token ahead. Lexical
 /// ambiguity, where a head may be followed by multiple different tokens, is
@@ -430,7 +431,7 @@ pub struct Parent<'i, I: Input + ?Sized, P, TK: Copy> {
     pub root_node: NodeIndex,
     pub head_node: NodeIndex,
 
-    /// This models ambiguity. RefCell is needed as we need an Interior
+    /// This models ambiguity. `RefCell` is needed as we need an Interior
     /// Mutability pattern to add new possibilities as they are discovered while
     /// keeping the rest of the structure immutable.
     pub possibilities: RefCell<Vec<Rc<SPPFTree<'i, I, P, TK>>>>,
@@ -467,7 +468,7 @@ impl<'i, I: Input + ?Sized, P, TK: Copy> Parent<'i, I, P, TK> {
 
     /// Number of possible solutions in this parent link.
     ///
-    /// If there >1 solutions we have ambiguity on the span of input covered by
+    /// If there >1 solutions we have ambiguity along the input span covered by
     /// this parent link.
     pub fn solutions(&self) -> usize {
         self.possibilities
@@ -623,15 +624,14 @@ impl<'i, I: Input + ?Sized, P, TK: Copy> Tree<'i, I, P, TK> {
     // TODO: Implement iteration
 }
 
-/// Shared packed forest returned by the GLR parser.
+/// Shared Packed Parse Forest (SPPF) returned by the GLR parser.
 ///
-/// A forest is an ordered collection of trees.
-/// Basically, a wrapper around GSS structure to provide information about
-/// number of trees/solutions, ambiguities and to provide tree
-/// extraction/navigation.
+/// A forest is an ordered collection of trees. Basically, a wrapper around GSS
+/// structure to provide information about number of trees/solutions,
+/// ambiguities and to provide tree extraction/navigation.
 ///
-/// Trees of the forest are ordered and each tree can be extracted as either
-/// an eager or a lazy tree given its index.
+/// Trees of the forest are ordered and each tree can be extracted as either an
+/// eager or a lazy tree given its index.
 #[derive(Debug)]
 pub struct Forest<'i, I: Input + ?Sized, P, TK: Copy> {
     /// Root nodes of trees which are possible solutions.

rustemo/src/lexer.rs

@@ -6,10 +6,10 @@ use colored::*;
 use core::fmt::Debug;
 use std::marker::PhantomData;
 
-/// The `Lexer` trait allows input tokenization
+/// The trait implemented by all Rustemo lexers
 ///
-/// Lexer is stateless and its job is to produce next token given the current
-/// context.
+/// Lexer is stateless and its job is to produce the next token given the
+/// current context.
 ///
 /// # Generic types
 ///
@@ -46,6 +46,8 @@ where
         'a: 'i;
 }
 
+/// The trait implemented by types used to recognize tokens in string inputs.
+/// Used by [`StringLexer`].
 pub trait TokenRecognizer<'i> {
     fn recognize(&self, _input: &'i str) -> Option<&'i str> {
         panic!("Recognize is not defined.")
@@ -197,7 +199,7 @@ where
     }
 }
 
-/// `Token` represent a single token from the input stream.
+/// Represents a single token from the input stream.
 pub struct Token<'i, I: Input + ?Sized, TK> {
     pub kind: TK,
 

rustemo/src/location.rs

@@ -63,7 +63,7 @@ impl Display for Position {
     }
 }
 
-/// `Location` describes a span from start till end in the parsed input.
+/// Describes a span from start till end in the parsed input.
 ///
 /// Start is mandatory while the end is not.
 ///

rustemo/src/lr/builder.rs

@@ -107,6 +107,7 @@ where
     }
 }
 
+/// A node in the generic tree produced by [`TreeBuilder`]
 #[derive(Debug)]
 pub enum TreeNode<'i, I, P, TK>
 where
@@ -124,8 +125,8 @@ where
     },
 }
 
-/// This builder returns a slice of the matched input. If no match is possible
-/// `None` is returned.
+/// Returns a slice of the matched input. If no match is possible `None` is
+/// returned.
 ///
 /// This is used by default for layout parsing where we don't need to keep the
 /// structure of the parsed layout but we need just the content as a slice of

rustemo/src/lr/context.rs

@@ -5,6 +5,7 @@ use crate::{
     parser::State,
 };
 
+/// [`Context`] implementation for LR parsing
 #[derive(Debug)]
 pub struct LRContext<'i, I: Input + ?Sized, S, TK> {
     position: usize,

rustemo/src/parser.rs

@@ -2,6 +2,7 @@ use std::path::Path;
 
 use crate::{context::Context, error::Result, input::Input, lexer::Lexer};
 
+/// The trait implemented by all Rustemo parsers.
 pub trait Parser<'i, I, C, L, S, TK>
 where
     I: Input + ?Sized,
@@ -28,8 +29,8 @@ where
 
     /// A convenience method for loading the content from the given file and
     /// calling `parse`. The parser will own the content being parsed and thus
-    /// has to outlive the output if the output is borrowed from the content
-    /// loaded from the file.
+    /// has to outlive `Self::Output` if it borrows from the content loaded from
+    /// the file.
     fn parse_file<'a, F: AsRef<Path>>(
         &'a mut self,
         file: F,