From d28b97aaffb3a1925d094daf095816a441e5d7a0 Mon Sep 17 00:00:00 2001 From: Yehor KOROTENKO <60360745+DobbiKov@users.noreply.github.com> Date: Tue, 24 Jun 2025 14:34:46 +0200 Subject: [PATCH] Add comprehensive inline documentation --- src/helper.rs | 2 ++ src/logger/archivation.rs | 5 +++++ src/logger/file_handler.rs | 6 ++++++ src/logger/file_handler/file_formatter.rs | 12 +++++++++++ src/logger/file_handler/file_manager.rs | 11 ++++++++++ src/logger/file_handler/file_name.rs | 13 ++++++++++-- src/logger/formatter.rs | 25 +++++++++++++++++++++-- src/logger/from_env.rs | 6 ++++++ src/logger/from_file_config.rs | 7 +++++-- src/logger/set_errors.rs | 3 +++ 10 files changed, 84 insertions(+), 6 deletions(-) diff --git a/src/helper.rs b/src/helper.rs index b77b2f4..3332f9a 100644 --- a/src/helper.rs +++ b/src/helper.rs @@ -1,3 +1,5 @@ +//! Internal helper functions for time handling and file I/O. + use chrono::{self, Datelike, Timelike}; use std::io::Write; use thiserror::Error; diff --git a/src/logger/archivation.rs b/src/logger/archivation.rs index f4b8046..2ee7fb6 100644 --- a/src/logger/archivation.rs +++ b/src/logger/archivation.rs @@ -1,3 +1,8 @@ +//! Helper utilities for log file archiving. +//! +//! This module exposes functions to determine archive locations and ensure +//! directories are created when needed. + use std::path::PathBuf; use crate::CONFIG; diff --git a/src/logger/file_handler.rs b/src/logger/file_handler.rs index 0841e9d..eb42bae 100644 --- a/src/logger/file_handler.rs +++ b/src/logger/file_handler.rs @@ -1,3 +1,9 @@ +//! Infrastructure for log file output. +//! +//! This module groups together helpers responsible for formatting log file +//! names, managing file rotation and compression, and writing log entries to +//! disk. + pub(crate) mod file_formatter; pub(crate) mod file_manager; pub(crate) mod file_name; diff --git a/src/logger/file_handler/file_formatter.rs b/src/logger/file_handler/file_formatter.rs index f380105..394a5f1 100644 --- a/src/logger/file_handler/file_formatter.rs +++ b/src/logger/file_handler/file_formatter.rs @@ -1,13 +1,21 @@ +//! Parser for file name templates used when creating log files. +//! +//! [`FileFormatter`] validates that a user supplied pattern is safe for file +//! creation and produces a sequence of [`LogPart`]s that can later be expanded +//! into a concrete file name. + use crate::logger::formatter::LogPart; use thiserror::Error; #[derive(Clone, Debug)] +/// Internal representation of a validated file name pattern. pub(crate) struct FileFormatter { pub(crate) format: Vec, } #[derive(Debug, Error)] +/// Errors that can occur while parsing a file name template. pub enum FileFormatterTryFromStringError { #[error("an incorrect character given: {0}")] IncorrectCharacterGiven(char), @@ -26,6 +34,10 @@ impl FileFormatter { fn forbidden_characters() -> [char; 4] { ['<', '>', '&', '%'] } + /// Parses a template string into a [`FileFormatter`]. + /// + /// Ensures that only allowed placeholders are present and that the + /// resulting file name ends with a valid extension (`.txt` or `.log`). pub(crate) fn try_from_string( format: &str, ) -> Result { diff --git a/src/logger/file_handler/file_manager.rs b/src/logger/file_handler/file_manager.rs index 9f79fd1..d693e16 100644 --- a/src/logger/file_handler/file_manager.rs +++ b/src/logger/file_handler/file_manager.rs @@ -1,3 +1,9 @@ +//! Handles creation, rotation and optional compression of log files. +//! +//! [`FileManager`] keeps track of the current log file and ensures it is +//! rotated when constraints are met (time, size or period). It is an internal +//! component used by the higher level configuration functions in [`crate::logger`]. + use std::{ fs::File, io::{self, BufReader}, @@ -19,6 +25,10 @@ use super::{ }; #[derive(Clone, Debug)] +/// Central structure responsible for writing log records to files. +/// +/// It owns the current log file and metadata used to decide when a new file +/// should be created. pub(crate) struct FileManager { file_format: FileFormatter, file_name: FileName, @@ -27,6 +37,7 @@ pub(crate) struct FileManager { } #[derive(Error, Debug)] +/// Errors produced when creating a [`FileManager`] from a format string. pub enum FileManagerFromStringError { #[error("string parsing for the file format error: {0}")] FileFormatParsingError(FileFormatterTryFromStringError), diff --git a/src/logger/file_handler/file_name.rs b/src/logger/file_handler/file_name.rs index 3f5f5cb..693e52b 100644 --- a/src/logger/file_handler/file_name.rs +++ b/src/logger/file_handler/file_name.rs @@ -1,3 +1,9 @@ +//! Representation and manipulation of log file names. +//! +//! [`FileName`] constructs a concrete file name from a pattern provided by +//! [`FileFormatter`]. It also supports incrementing the name when multiple files +//! with the same base name are created. + use crate::{helper, Level}; use crate::logger::formatter::LogPart; @@ -5,6 +11,7 @@ use crate::logger::formatter::LogPart; use super::file_formatter::FileFormatter; use thiserror::Error; #[derive(Debug, Clone)] +/// File name generated from a [`FileFormatter`] pattern. pub(crate) struct FileName { file_name: String, file_num: Option, @@ -12,6 +19,7 @@ pub(crate) struct FileName { } #[derive(Debug, Error)] +/// Errors that can occur while converting a [`FileFormatter`] into a file name. pub enum FileNameFromFileFormatterError { #[error("no fomrat provided")] NoFormatProvided, @@ -39,7 +47,7 @@ impl FileName { Some(num) => self.file_num = Some(num + 1), }; } - // pub(crate) + /// Expands a list of [`LogPart`] values into a concrete file name string. pub fn get_string_from_log_parts(parts: Vec, level: Level) -> String { let time_str = helper::get_current_time_in_string(); let date_str = helper::get_current_date_in_string(); @@ -59,7 +67,7 @@ impl FileName { } res } - //pub(crate) + /// Build a [`FileName`] from a [`FileFormatter`] using the provided log level. pub fn from_file_formatter( format: FileFormatter, level: Level, @@ -99,6 +107,7 @@ impl FileName { file_extension: extension.to_string(), }) } + /// Returns the full file name including any appended index and extension. pub(crate) fn get_full_file_name(&self) -> String { String::from(self.to_owned()) } diff --git a/src/logger/formatter.rs b/src/logger/formatter.rs index 1942cad..e4b0458 100644 --- a/src/logger/formatter.rs +++ b/src/logger/formatter.rs @@ -1,6 +1,13 @@ +//! Utilities for parsing user provided log formatting templates. +//! +//! This module converts strings like `"[{level}] {message}"` into +//! [`LogFormatter`] structures used internally by the logger. It exposes +//! helper enums and functions to interpret color tags and placeholder blocks. + use thiserror::Error; #[derive(Clone, Copy, PartialEq, Eq, Debug)] +/// Colors that can be applied to portions of a formatted log message. pub(crate) enum LogColor { Red, Green, @@ -56,6 +63,7 @@ impl LogColor { } #[derive(Debug, Clone, PartialEq, Eq)] +/// A single placeholder or text fragment parsed from a format string. pub(crate) enum LogPart { Message, Time, @@ -99,17 +107,27 @@ impl From for LogPart { } #[derive(Debug, Clone, PartialEq, Eq)] +/// Internal helper tying a [`LogPart`] with an optional [`LogColor`]. pub(crate) struct LogFormatWrapper { pub(crate) color: Option, pub(crate) part: LogPart, } #[derive(Debug, Clone, PartialEq, Eq)] +/// Representation of a parsed format string. +/// +/// The struct stores a sequence of [`LogFormatWrapper`] elements that +/// correspond to the parts of the user provided template. pub(crate) struct LogFormatter { pub(crate) parts: Vec, } impl LogFormatter { + /// Parses a format template into a [`LogFormatter`]. + /// + /// # Errors + /// Returns [`ParseStringToWrappersError`] when the string contains + /// unsupported placeholders or malformed color tags. pub(crate) fn parse_from_string(text: &str) -> Result { let wrappers = parse_string_to_wrappers(text)?; Ok(LogFormatter { parts: wrappers }) @@ -130,7 +148,10 @@ pub enum ParseStringToWrappersError { UnableToParsePartsToFormatter(ParsePartsToFormatterError), } -/// Parse string to log_wrappers i.e Vec of log_part and assigned color to it +/// Parses a template into a vector of [`LogFormatWrapper`]s. +/// +/// The returned wrappers combine [`LogPart`] placeholders with optional +/// [`LogColor`] information extracted from angle bracket tags. pub(crate) fn parse_string_to_wrappers( text: &str, ) -> Result, ParseStringToWrappersError> { @@ -146,7 +167,7 @@ pub(crate) fn parse_string_to_wrappers( .map_err(ParseStringToWrappersError::UnableToParsePartsToFormatter) } -/// Parse string to log_parts +/// Converts a template into a simple list of [`LogPart`]s. pub(crate) fn parse_string_to_logparts( text: &str, ) -> Result, ParseStringToWrappersError> { diff --git a/src/logger/from_env.rs b/src/logger/from_env.rs index 3ecf67c..d42725c 100644 --- a/src/logger/from_env.rs +++ b/src/logger/from_env.rs @@ -1,3 +1,8 @@ +//! Load configuration options from environment variables. +//! +//! The variables follow the same naming as the configuration file fields, such +//! as `level`, `print_to_terminal` or `file_name`. + use std::env; use crate::logger::from_file_config::{parse_inter_config_from_serde_config, ConfigForSerde}; @@ -62,6 +67,7 @@ fn parse_config_from_env() -> Result { Ok(res_conf) } +/// Read environment variables and apply them to the logger configuration. pub(crate) fn load_config_from_env() -> Result<(), ReadFromConfigFileError> { let serde_conf = parse_config_from_env()?; let inter_conf = parse_inter_config_from_serde_config(serde_conf) diff --git a/src/logger/from_file_config.rs b/src/logger/from_file_config.rs index e75ed10..e93494f 100644 --- a/src/logger/from_file_config.rs +++ b/src/logger/from_file_config.rs @@ -1,5 +1,7 @@ -// this module aims to provide a feature of setting the config up from a file (without explicitely -// precising it in the file (but make it still possible)) +//! Parse configuration files in `ini`, `json` or `env` formats. +//! +//! The resulting settings are converted into [`crate::logger`] configuration +//! using [`InterConfig`]. use std::io::Read; @@ -392,6 +394,7 @@ pub(crate) fn parse_inter_config_from_serde_config( s_conf.try_into() } +/// Load configuration from the specified file and apply it to the logger. pub(crate) fn load_config_from_file(path: &str) -> Result<(), ReadFromConfigFileError> { let parse_conf = parse_config_file(path)?; let inter_conf = parse_inter_config_from_serde_config(parse_conf) diff --git a/src/logger/set_errors.rs b/src/logger/set_errors.rs index b7676a0..d6030d6 100644 --- a/src/logger/set_errors.rs +++ b/src/logger/set_errors.rs @@ -1,3 +1,5 @@ +//! Error types used throughout the configuration helpers. + use crate::logger; use thiserror::Error; @@ -6,6 +8,7 @@ use super::{ }; #[derive(Debug, thiserror::Error)] +/// Errors while accessing or mutating the global configuration. pub enum AccessError { #[error("unable to load config")] LoadConfig,