chore: add documentation

Author: Wybxc

parse-it/src/lexer.rs

@@ -17,7 +17,9 @@ pub struct Span {
     pub end: usize,
 }
 
+/// A trait for types that can be converted to another type.
 pub trait TryConvert<T> {
+    /// Try to convert the value to the target type.
     fn try_convert(&self) -> Option<T>;
 }
 
@@ -27,6 +29,7 @@ impl<T: Copy> TryConvert<T> for T {
     }
 }
 
+/// Cursor position in the input.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Cursor {
     cursor: usize,
@@ -42,6 +45,7 @@ pub struct LexerState<'a> {
 }
 
 impl<'a> LexerState<'a> {
+    /// Create a new lexer state.
     pub fn new(input: &'a str) -> Self {
         Self {
             start: 0,
@@ -50,7 +54,7 @@ impl<'a> LexerState<'a> {
         }
     }
 
-    /// TODO
+    /// Run the lexer against the given regex.
     pub fn run(&mut self, regex: &Regex) -> Option<PatternID> {
         let input = Input::new(self.input)
             .range(self.cursor..)
@@ -61,7 +65,7 @@ impl<'a> LexerState<'a> {
         Some(end.pattern())
     }
 
-    /// TODO
+    /// Get the lexeme of the current token.
     pub fn lexeme(&self) -> &'a str {
         &self.input[self.start..self.cursor]
     }
@@ -74,17 +78,20 @@ impl<'a> LexerState<'a> {
         }
     }
 
+    /// Get the span of the current token.
     pub fn span(&self) -> Span {
         Span {
             start: self.start,
             end: self.cursor,
         }
     }
 
+    /// Check if the lexer is at the end of the input.
     pub fn is_empty(&self) -> bool {
         self.cursor >= self.input.len()
     }
 
+    /// Advance the lexer to the given cursor position.
     pub fn advance_to_cursor(&mut self, cursor: Cursor) {
         self.start = cursor.start;
         self.cursor = cursor.cursor;

parse-it/src/lib.rs

@@ -46,7 +46,7 @@
 //!     println!("{:?}", instrs);
 //! }
 //! ```
-// #![warn(missing_docs)]
+#![warn(missing_docs)]
 #![allow(clippy::needless_doctest_main)]
 
 pub mod lexer;
@@ -61,12 +61,15 @@ pub use crate::{
     parser::{Error, ParserState},
 };
 
-/// A lexer for the parser.
+/// A lexer.
 pub trait LexIt {
+    /// The token type.
     type Token<'a>;
 
+    /// Create a new lexer instance.
     fn new() -> Self;
 
+    /// Get the next token from the lexer.
     fn next<'a>(&self, lexbuf: &mut LexerState<'a>) -> Option<Self::Token<'a>>;
 }
 

parse-it/src/parser.rs

@@ -127,6 +127,7 @@ impl<'a, L: LexIt + Clone> ParserState<'a, L> {
         self.next().and_then(matches).ok_or_else(|| self.error())
     }
 
+    /// Parse a token that can be converted to the given type.
     pub fn parse_type<T>(&mut self) -> Result<T, Error>
     where
         L::Token<'a>: TryConvert<T>,
@@ -135,6 +136,7 @@ impl<'a, L: LexIt + Clone> ParserState<'a, L> {
         self.parse_with(|tt| tt.try_convert())
     }
 
+    /// Parse a token that exactly matches the given character.
     pub fn parse_char(&mut self, c: char) -> Result<char, Error> {
         self.next().ok_or_else(|| self.error())?;
         let lexeme = self.lexbuf.lexeme();
@@ -147,6 +149,7 @@ impl<'a, L: LexIt + Clone> ParserState<'a, L> {
         }
     }
 
+    /// Parse a token that exactly matches the given string.
     pub fn parse_str(&mut self, literal: &'a str) -> Result<&str, Error> {
         self.next().ok_or_else(|| self.error())?;
         let lexeme = self.lexbuf.lexeme();