(errors) add: doc

Author: t-webber

.github/workflows/rust.yml

@@ -48,3 +48,12 @@ jobs:
             - uses: actions/checkout@v4
             - name: Run tests
               run: cargo test --verbose
+
+    doc:
+        needs: install
+        runs-on: ubuntu-latest
+
+        steps:
+            - uses: actions/checkout@v4
+            - name: Check doc
+              run: cargo doc --document-private-items --all --verbose

src/errors/compile.rs

@@ -1,33 +1,61 @@
+use core::fmt;
+
 use crate::errors::api::Location;
 
+/// Struct to store the error information
+///
+/// # Creation
+///
+/// To create an error, you need to have the [`Location`] of the error. Then,
+/// use the methods on that location, for example:
+///
+/// ```ignore
+/// let location = Location::from("filename.c");
+/// let error = location.to_error("Something bad happened here.".to_owned());
+/// ```
+///
+/// To see the others methods to create errors see [`Location`].
+///
+/// # Usage
+///
+/// The [`CompileError`] is mainly used as part of a
+/// [`Res`](super::result::Res).
 #[derive(Debug)]
 pub struct CompileError {
+    /// Severity of the error
     err_lvl: ErrorLevel,
+    /// Length of the erroneous token or expression
     length: usize,
+    /// Location of the error in the C source file
     location: Location,
+    /// Error message to be displayed to the user
     message: String,
 }
 
 impl CompileError {
-    pub fn get(self) -> (Location, String, &'static str, usize) {
+    /// Returns the owned data of a `CompileError`.
+    pub(super) fn into_values(self) -> (Location, String, String, usize) {
         (
             self.location,
             self.message,
-            self.err_lvl.repr(),
+            self.err_lvl.to_string(),
             self.length,
         )
     }
 
-    pub fn is_error(&self) -> bool {
+    /// Checks if the error is of severity [`ErrorLevel::Error`].
+    pub(crate) fn is_error(&self) -> bool {
         self.err_lvl == ErrorLevel::Error
     }
 
-    pub fn specify_length(&mut self, length: usize) {
+    // Replaces length of the token or expression concerned by the `CompileError`.
+    pub(crate) fn specify_length(&mut self, length: usize) {
         self.length = length;
     }
 }
 
 impl From<(Location, String, ErrorLevel, usize)> for CompileError {
+    #[inline]
     fn from((location, message, err_lvl, length): (Location, String, ErrorLevel, usize)) -> Self {
         Self {
             err_lvl,
@@ -39,6 +67,7 @@ impl From<(Location, String, ErrorLevel, usize)> for CompileError {
 }
 
 impl From<(Location, String, ErrorLevel)> for CompileError {
+    #[inline]
     fn from((location, message, err_lvl): (Location, String, ErrorLevel)) -> Self {
         Self {
             message,
@@ -49,19 +78,44 @@ impl From<(Location, String, ErrorLevel)> for CompileError {
     }
 }
 
+/// Different levels of errors
 #[derive(Debug, PartialEq, Eq)]
 pub enum ErrorLevel {
+    /// The compiler stops compiling the current block and fails.
+    ///
+    /// The level is only `Error` when the compiler can't fix the error and
+    /// panics.
+    ///
+    /// The compiler will continue if it manages to do so safely on parts that
+    /// are independent from the original location of the error. Not all of the
+    /// independent parts are compiled though.
     Error,
+    /// Found a bad practice.
+    ///
+    /// # Examples
+    ///
+    /// - a leading space after `\` at end of line
     Suggestion,
+    /// The compiler manages to fix the code and continue.
+    ///
+    /// A warning is displayed to the user, but the compiler continues as
+    /// nothing happened.
+    ///
+    /// # Examples
+    ///
+    /// - an overflow on a integer constant: the value is crapped and the
+    ///   compiler continues
+    /// - deprecated behaviours (e.g. using `_Bool` instead of `bool` in C23).
     Warning,
 }
 
-impl ErrorLevel {
-    const fn repr(&self) -> &'static str {
+#[expect(clippy::min_ident_chars)]
+impl fmt::Display for ErrorLevel {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            Self::Warning => "warning",
-            Self::Error => "error",
-            Self::Suggestion => "suggestion",
+            Self::Error => "error".fmt(f),
+            Self::Suggestion => "suggestion".fmt(f),
+            Self::Warning => "warning".fmt(f),
         }
     }
 }

src/errors/display.rs

@@ -3,8 +3,11 @@ use std::collections::HashMap;
 
 use super::compile::CompileError;
 
-#[inline]
-pub fn display_errors(
+/// Transforms [`CompileError`] into a human-readable string
+///
+/// See [`Res::get_displayed_errors`](super::result::Res::get_displayed_errors)
+/// for extra information and examples.
+pub(super) fn display_errors(
     errors: Vec<CompileError>,
     files: &[(String, &str)],
     err_type: &str,
@@ -15,7 +18,7 @@ pub fn display_errors(
         files_status.insert(filename.to_owned(), content.lines().collect());
     }
     for error in errors {
-        let (location, message, err_lvl, length) = error.get();
+        let (location, message, err_lvl, length) = error.into_values();
         let (filename, line_nb, column_nb) = location.into_values();
         let code_lines = files_status
             .get(&filename)

src/errors/location.rs

@@ -2,6 +2,16 @@ use core::fmt;
 
 use super::compile::{CompileError, ErrorLevel};
 
+/// Struct to pinpoint a precise character in the C source file.
+///
+/// The locations are computed by the lexer that reads the C source file. Then,
+/// the locations are stored inside the tokens to keep them for the rest of the
+/// compiler.
+///
+/// # Note
+///
+/// In order to respect the click links from terminals, the line and column of
+/// a file start at 1 and not 0.
 #[derive(Debug, Clone)]
 pub struct Location {
     col: usize,
@@ -10,38 +20,53 @@ pub struct Location {
 }
 
 impl Location {
-    pub(crate) const fn get_values(&self) -> (&String, usize, usize) {
-        (&self.file, self.line, self.col)
-    }
-
+    /// Increments column of location by 1
+    ///
+    /// This is used by lexer when parsing every character of the C file.
     pub(crate) fn incr_col(&mut self) {
         self.col += 1;
     }
 
+    /// Increments line of location by 1
+    ///
+    /// This is used by lexer when parsing every line of the C file.
     pub(crate) fn incr_line(&mut self) {
         self.line += 1;
         self.col = 1;
     }
 
+    /// Creates an error from a location without cloning
     pub(crate) fn into_error(self, msg: String) -> CompileError {
         CompileError::from((self, msg, ErrorLevel::Error))
     }
 
+    /// Moves the location back a few character on the current line
+    ///
+    /// If the offset is too big, the column is set to minimal (1) without any
+    /// warnings or errors.
     pub(crate) fn into_past(self, offset: usize) -> Self {
         Self {
             col: self.col.checked_sub(offset).unwrap_or(1),
             ..self
         }
     }
 
+    /// Returns the owned data of a `Location`.
     pub(crate) fn into_values(self) -> (String, usize, usize) {
         (self.file, self.line, self.col)
     }
 
+    /// Creates an error by cloning the location.
     pub(crate) fn to_error(&self, msg: String) -> CompileError {
         CompileError::from((self.to_owned(), msg, ErrorLevel::Error))
     }
 
+    /// Returns a clone of the current file name.
+    pub(crate) fn to_filename(&self) -> String {
+        self.file.clone()
+    }
+
+    /// Creates an warning by cloning the location.
     pub(crate) fn to_suggestion(&self, msg: String) -> CompileError {
         CompileError::from((self.to_owned(), msg, ErrorLevel::Warning))
     }

src/errors/mod.rs

@@ -1,3 +1,9 @@
+//! Module to deal with compiler errors
+//!
+//! This module provides the tools to store the information on errors during
+//! compile-time and display these errors to the user at the end of the
+//! compilation process.
+
 pub mod api {
     #![allow(clippy::pub_use)]
 

src/errors/result.rs

@@ -5,19 +5,64 @@ use super::display::display_errors;
 
 type PublicRes<T> = (T, Vec<CompileError>);
 
+/// Struct to store the errors, whilst still having the desired value.
+///
+/// This struct is meant as a [`Result`], but with the were it is possible to
+/// have a value and some errors at the same time. It is for example the case
+/// for warnings and suggestions (see
+/// [`CompileError`] for more information), that must be stored, and at the
+/// same time, the compiler continues to work.
 #[derive(Debug)]
 pub struct Res<T> {
     errors: Vec<CompileError>,
     result: T,
 }
 
 impl<T> Res<T> {
+    /// Returns all the errors in a user-readable format.
+    ///
+    /// # Returns
+    ///
+    /// A [`String`] containing all the errors, displayed in a user-readable
+    /// format, with a clickable location, and an explanation message.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::fs;
+    ///
+    /// use c_parser::{lex_file, Location};
+    ///
+    /// let content = "int m@in() { }";
+    /// let res = lex_file(&content, &mut Location::from("filename.c"));
+    /// let errors = res.get_displayed_errors(&[("filename.c".to_owned(), content)], "lexer");
+    /// let expected =
+    ///     "filename.c:1:6: lexer error: Character '@' not supported in context of a 'identifier'.
+    ///     1 | int m@in() { }
+    ///              ^
+    /// ";
+    ///
+    /// assert!(errors == expected, "!{errors}!\n!{expected}!");
+    /// ```  
+    ///
+    /// # Panics
+    ///
+    /// If there is at least one error of level `Error`.
     #[inline]
     pub fn get_displayed_errors(self, files: &[(String, &str)], err_type: &str) -> String {
         display_errors(self.errors, files, err_type)
-            .expect("Buffer overflow, failed to fecth errors")
+            .expect("Buffer overflow, failed to fetch errors")
     }
 
+    /// Prints all the errors to the user.
+    ///
+    /// # Returns
+    ///
+    /// The value of the [`Res`] if there aren't any errors of level `Error`.
+    ///
+    /// # Panics
+    ///
+    /// If there is at least one error of level `Error`.
     #[inline]
     #[expect(clippy::print_stderr)]
     pub fn unwrap_or_display(self, files: &[(String, &str)], err_type: &str) -> T {
@@ -31,13 +76,15 @@ impl<T> Res<T> {
 }
 
 impl<T: Default> Res<T> {
+    /// Creates a [`Res`] from one error
     pub(crate) fn from_err(err: CompileError) -> Self {
         Self {
             result: T::default(),
             errors: vec![err],
         }
     }
 
+    /// Creates a [`Res`] from a list of errors
     pub(crate) fn from_errors(errors: Vec<CompileError>) -> Self {
         Self {
             result: T::default(),

src/lib.rs

@@ -59,7 +59,7 @@ mod lexer;
 mod parser;
 
 #[expect(clippy::useless_attribute, clippy::pub_use)]
-pub use crate::errors::api::{Location, Res};
+pub use crate::errors::api::{CompileError, Location, Res};
 #[expect(clippy::useless_attribute, clippy::pub_use)]
 pub use crate::lexer::api::{display_tokens, lex_file, Number, TokenValue};
 #[expect(clippy::useless_attribute, clippy::pub_use)]

src/parser/parse_content.rs

@@ -92,9 +92,7 @@ pub fn parse_block(
 #[inline]
 pub fn parse_tokens(tokens: Vec<Token>) -> Res<Ast> {
     let mut nodes = vec![];
-    let filename = tokens
-        .first()
-        .map(|node| node.get_location().get_values().0.to_owned());
+    let filename = tokens.first().map(|node| node.get_location().to_filename());
     let mut tokens_iter = tokens.into_iter();
     while tokens_iter.len() != 0 {
         let mut outer_node_block = Ast::Block(Block::default());

src/parser/tree/node.rs

@@ -211,7 +211,7 @@ impl Ast {
         }
     }
 
-    /// Adds the colon of a [`super::TernaryOperator`].
+    /// Adds the colon of a [`TernaryOperator`](super::TernaryOperator).
     ///
     /// This method finds a ternary operator, and changes its reading state to
     /// failure.
@@ -266,9 +266,9 @@ impl Ast {
 
     /// Make an [`Ast`] a LHS node
     ///
-    /// This is called when an assign [`super::Operator`] is created or a
-    /// function is created, to convert `*` to a type attribute. It also
-    /// check that the [`Ast`] is a valid LHS.
+    /// This is called when an assign [`Operator`](super::Operator) is created
+    /// or a function is created, to convert `*` to a type attribute. It
+    /// also check that the [`Ast`] is a valid LHS.
     pub fn make_lhs(&mut self) -> Result<(), String> {
         self.make_lhs_aux(false)
     }