(lexer) fix: missing doc in private items

Author: t-webber

src/errors/location.rs

@@ -69,11 +69,6 @@ impl Location {
         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 suggestion by cloning the location.
     pub(crate) fn to_suggestion(&self, msg: String) -> CompileError {
         CompileError::from((self.to_owned(), msg, ErrorLevel::Warning))

src/lexer/lex_content.rs

@@ -1,3 +1,7 @@
+//! Module that implements the functions that lex raw strings.
+//!
+//! See [`lex_file`] for more information.
+
 #[allow(clippy::enum_glob_use)]
 use LexingState::*;
 
@@ -7,6 +11,10 @@ use super::state::api::{
 use super::types::api::{LexingData, Token};
 use crate::errors::api::{Location, Res};
 
+/// Function to manage one character.
+///
+/// This function updates the [`LexingState`] automaton, and executes the right
+/// handlers.
 #[expect(clippy::too_many_lines)]
 fn lex_char(
     ch: char,
@@ -149,6 +157,10 @@ fn lex_char(
     }
 }
 
+/// Function that lexes a whole source file.
+///
+/// This function creates the automaton and the data to be modified by the other
+/// functions. Every character is parsed one by one by [`lex_char`].
 #[inline]
 pub fn lex_file(content: &str, location: &mut Location) -> Res<Vec<Token>> {
     let mut lex_data = LexingData::default();
@@ -162,6 +174,10 @@ pub fn lex_file(content: &str, location: &mut Location) -> Res<Vec<Token>> {
     lex_data.into_res()
 }
 
+/// Function that lexes one line.
+///
+/// It stops at the first erroneous character, or at the end of the line if
+/// everything was ok.
 fn lex_line(
     line: &str,
     location: &mut Location,

src/lexer/numbers/base/binary.rs

@@ -1,3 +1,5 @@
+//! Module to parse binary-represented number constants
+
 use super::super::macros::parse_int_from_radix;
 use super::super::parse::OverParseRes;
 #[allow(clippy::wildcard_imports)]

src/lexer/numbers/base/decimal.rs

@@ -1,3 +1,5 @@
+//! Module to parse decimal-represented number constants
+
 use core::num::ParseFloatError;
 use core::str::FromStr;
 
@@ -7,6 +9,8 @@ use super::super::types::arch_types::*;
 use super::super::types::{ERR_PREFIX, Number, NumberType};
 use crate::errors::api::{CompileError, Location};
 
+/// Parses the stringifies version of a decimal number in a specific integer
+/// or floating point type.
 macro_rules! parse_number {
     ($location:ident, $nb_type:ident, $literal:tt, $($int:ident)*, $($float:ident)*) => {
         match $nb_type {
@@ -17,6 +21,8 @@ macro_rules! parse_number {
     };
 }
 
+/// Parses the stringifies version of decimal number in a specific floating
+/// point type.
 fn parse_and_error<T>(literal: &str, location: &Location) -> Result<T, CompileError>
 where
     T: FromStr,

src/lexer/numbers/base/hexadecimal.rs

@@ -1,3 +1,5 @@
+//! Module to parse hexadecimal-represented number constants
+
 #![allow(clippy::arbitrary_source_item_ordering)]
 
 use super::super::macros::parse_int_from_radix;
@@ -7,13 +9,14 @@ use super::super::types::arch_types::*;
 use super::super::types::{ERR_PREFIX, Number, NumberType};
 use crate::errors::api::{CompileError, Location};
 
+/// Implements the [`FloatingPoint`] for the floating-point types.
 macro_rules! impl_floating_point {
-    ($x:expr, $($ftype:ident)*) => {
+    ($x:expr, $($type:ident)*) => {
         $(#[expect(clippy::as_conversions, clippy::cast_precision_loss)]
-        impl FloatingPoint<concat_idents!($ftype, IntPart)> for $ftype {
+        impl FloatingPoint<concat_idents!($type, IntPart)> for $type {
             const MANTISSA_SIZE: u32 = $x;
 
-            type Unsigned = concat_idents!($ftype, IntPart);
+            type Unsigned = concat_idents!($type, IntPart);
 
 
             fn from_unsigned(
@@ -39,6 +42,7 @@ macro_rules! impl_floating_point {
     };
 }
 
+/// Parses the stringified version of a number into a [`HexFloatData`].
 macro_rules! parse_hexadecimal_float {
     ($overflow:expr, $nb_type:ident, $float_parse:ident, $($t:ident)*) => {{
         match $nb_type {
@@ -71,9 +75,17 @@ impl_floating_point!(23, Double Float LongDouble);
 ///
 /// ``overflow`` is set to true if the value doesn't fix in the mantissa.
 trait FloatingPoint<T> {
+    /// Size of the mantissa
+    ///
+    /// In the binary representation of the floating-point
+    /// values, there is one part for the exponent, and one point for the
+    /// digits, the latter is called 'mantissa'.
     const MANTISSA_SIZE: u32;
+    /// The biggest unsigned integer type that can contain the mantissa.
     type Unsigned;
+    /// Convert the integer-parsed value into the current floating-point type.
     fn from_unsigned(val: T, overflow: &mut bool) -> Self;
+    /// Convert the usize-parsed value into the current floating-point type.
     fn from_usize(val: usize, overflow: &mut bool) -> Self;
 }
 
@@ -100,6 +112,7 @@ struct HexFloatData {
 }
 
 impl HexFloatData {
+    /// Pushes a character to the current state.
     fn push(&mut self, ch: char) {
         match self.state {
             HexFloatParseState::Int => self.int_part.push(ch),
@@ -108,6 +121,7 @@ impl HexFloatData {
         }
     }
 
+    /// Returns the exponent of the number constant.
     fn get_exp(&self) -> u32 {
         if self.exponent.is_empty() {
             0
@@ -125,8 +139,18 @@ impl HexFloatData {
 /// and a exponent part after an exponent character ('p').
 #[derive(Default, PartialEq, Eq, Debug)]
 enum HexFloatParseState {
+    /// Decimal part
+    ///
+    /// The part between the full stop and the exponent character 'p' (if they
+    /// exist).
     Decimal,
+    /// Exponent part
+    ///
+    /// Last part of the string, after the 'p' character.
     Exponent,
+    /// Integer part
+    ///
+    /// First part of the string, before the full stop and the 'p' character.
     #[default]
     Int,
 }

src/lexer/numbers/base/mod.rs

@@ -1,3 +1,5 @@
+//! Module to parse number constants, respectively to a base and a type.
+
 pub mod binary;
 pub mod decimal;
 pub mod hexadecimal;

src/lexer/numbers/base/octal.rs

@@ -1,3 +1,5 @@
+//! Module to parse octal-represented number constants
+
 use super::super::macros::parse_int_from_radix;
 use super::super::parse::OverParseRes;
 #[allow(clippy::wildcard_imports)]

src/lexer/numbers/from_literal.rs

@@ -1,3 +1,6 @@
+//! Module that tries to convert a string into a valid constant C number,
+//! whatever the size, type and encoding base.
+
 use core::str;
 
 use super::super::types::api::{Ident, LexingData};

src/lexer/numbers/macros.rs

@@ -1,6 +1,13 @@
+//! Module that defines useful macros to parse integer and get useful errors.
+
 #![allow(clippy::arbitrary_source_item_ordering)]
 #![allow(clippy::pub_use)]
 
+/// Parses an integer from a given base
+///
+/// Specify the base with the radix integer, that is 2, 8 or 16.
+///
+/// For base 10, please use [`safe_parse_int`] for better errors.
 macro_rules! parse_int_from_radix {
     ($location:ident, $nb_type:ident, $literal:tt, $reason:expr, $radix:expr, $($t:ident)*) => {{
         use $crate::lexer::numbers::{macros::safe_parse_int, parse::OverParseRes};
@@ -12,6 +19,7 @@ macro_rules! parse_int_from_radix {
     }};
 }
 
+/// Parses an decimal integer from a string
 macro_rules! safe_parse_int {
     ($err_prefix:expr, $dest_type:ident, $location:ident, $function_call:expr) => {{
         use $crate::lexer::numbers::api::OverParseRes;

src/lexer/numbers/parse.rs

@@ -1,3 +1,6 @@
+//! Module that defines the result and error types used for parsing a number
+//! constant.
+
 use core::{convert, fmt, ops};
 
 use super::types::Number;
@@ -12,10 +15,15 @@ use crate::errors::api::{CompileError, Location};
 /// If an error occurs, the overflows are ignored (overflows are only warnings
 /// not errors.)
 pub enum OverParseRes<T> {
+    /// Number parsing failed
     Err(CompileError),
+    /// Number parsing overflowed
     Overflow,
+    /// Number parsing succeeded
     Value(T),
+    /// Number parsing succeeded; but with a warning
     ValueErr(T, CompileError),
+    /// Number parsing succeeded; but with an overflow
     ValueOverflow(T),
 }
 
@@ -118,8 +126,11 @@ impl ops::FromResidual<Result<convert::Infallible, CompileError>> for OverParseR
 /// This is the equivalent of [`OverParseRes`], but were the overflows were
 /// transformed into warnings.
 pub enum ParseRes<T> {
+    /// Number parsing failed
     Err(CompileError),
+    /// Number parsing succeeded
     Value(T),
+    /// Number parsing succeeded; but with a warning
     ValueErr(T, CompileError),
 }