From cbd0717cc6c28c344b952f07896cf4f5ae3f33b5 Mon Sep 17 00:00:00 2001 From: PlexSheep Date: Wed, 20 Sep 2023 20:14:10 +0200 Subject: [PATCH] fix log and math docu --- Cargo.toml | 3 --- members/pt-log/Cargo.toml | 1 - members/pt-log/src/error.rs | 14 ++++--------- members/pt-log/src/lib.rs | 40 ++++++++++++++----------------------- members/pt-math/src/lib.rs | 10 ++-------- 5 files changed, 21 insertions(+), 47 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 63e17d2..9a8f186 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -61,9 +61,6 @@ hedu = ["bintols"] [lib] name = "libpt" -# I chose a bad name for my package and i will have to live with it. -# make issue here to make it possible to name the lib file in cargo -# https://github.com/rust-lang/cargo/issues/1970 crate-type = [ "dylib", # .dll, .so, .dynlib "staticlib" # .lib, .a diff --git a/members/pt-log/Cargo.toml b/members/pt-log/Cargo.toml index 37cbe63..0fa9818 100644 --- a/members/pt-log/Cargo.toml +++ b/members/pt-log/Cargo.toml @@ -16,7 +16,6 @@ categories.workspace = true tracing = "0.1.37" tracing-appender = "0.2.2" tracing-subscriber = "0.3.17" -env_logger = "0.10.0" pyo3 = {workspace = true} [dev-dependencies] diff --git a/members/pt-log/src/error.rs b/members/pt-log/src/error.rs index 435ee9f..94db124 100644 --- a/members/pt-log/src/error.rs +++ b/members/pt-log/src/error.rs @@ -1,12 +1,6 @@ -//! # very short description +//! # Error module for [`pt-log`](crate) //! -//! Short description -//! -//! Details -//! -//! ## Section 1 -//! -//! ## Section 2 +//! This module handles errors in logging contexts. //// ATTRIBUTES //////////////////////////////////////////////////////////////////////////////////// // we want docs @@ -22,7 +16,7 @@ use pyo3::{exceptions::PyException, PyErr}; use tracing::subscriber::SetGlobalDefaultError; //// TYPES ///////////////////////////////////////////////////////////////////////////////////////// -/// a quick alias for a result with a [`LoggerError`] +/// a quick alias for a result with a [`Error`] pub type Result = std::result::Result; //// CONSTANTS ///////////////////////////////////////////////////////////////////////////////////// @@ -32,7 +26,7 @@ pub type Result = std::result::Result; //// MACROS //////////////////////////////////////////////////////////////////////////////////////// //// ENUMS ///////////////////////////////////////////////////////////////////////////////////////// -/// ## Errors for the [logger](crate::logger) +/// ## Errors for the [Logger](super::Logger) pub enum Error { /// Bad IO operation IO(std::io::Error), diff --git a/members/pt-log/src/lib.rs b/members/pt-log/src/lib.rs index 785c403..0cc0161 100644 --- a/members/pt-log/src/lib.rs +++ b/members/pt-log/src/lib.rs @@ -1,14 +1,15 @@ -//! # A specialized Logger for [`pt`](crate) +//! # A specialized Logger for [`pt`](../libpt/index.html) //! -//! For the library version, only the basic [`log`] is used, so that it is possible for -//! the end user to use the [`log`] frontend they desire. +//! For the library version, only the basic [`tracing`] is used, so that it is possible for +//! the end user to use the [`tracing`] frontend they desire. //! //! I did however decide to create a [`Logger`] struct. This struct is mainly intended to be used -//! with the python module of [`pt`](crate), but is still just as usable in other contexts. +//! with the python module of [`pt`](../libpt/index.html), but is still just as usable in other contexts. //! //! ## Technologies used for logging: -//! - [`log`]: base logging crate -//! - [`env_logger`]: used for the executable +//! - [`tracing`]: base logging crate +//! - [`tracing_appender`]: Used to log to files +//! - [`tracing_subscriber`]: Used to do actual logging, formatting, to stdout //// ATTRIBUTES //////////////////////////////////////////////////////////////////////////////////// @@ -39,21 +40,10 @@ pub const DEFAULT_LOG_DIR: &'static str = "/dev/null"; static INITIALIZED: AtomicBool = AtomicBool::new(false); //// STRUCTS /////////////////////////////////////////////////////////////////////////////////////// -/// ## Logger for [`pt`](crate) +/// ## Logger for [`pt`](../libpt/index.html) /// /// This struct exists mainly for the python module, so that we can use the same logger with both /// python and rust. -/// -/// ### Setting a [`Level`](log::Level) -/// -/// To set a [`Level`](log::Level), you need to set the environment variable `LIBPT_LOGLEVEL` -/// to either of: -/// -/// - `Trace` -/// - `Debug` -/// - `Info` -/// - `Warn` -/// - `Error` #[pyclass] pub struct Logger {} @@ -71,7 +61,7 @@ impl Logger { /// /// Will enable the logger to be used. /// - /// Assumes some defaults, use [`init_customized`](init_customized) for more control + /// Assumes some defaults, use [`init_customized`](Self::init_customized) for more control pub fn init(log_dir: Option, max_level: Option) -> Result<()> { Self::init_customized( log_dir.is_some(), @@ -154,35 +144,35 @@ impl Logger { } } - /// ## logging at [`Level::Error`] + /// ## logging at [`Level::ERROR`] pub fn error(&self, printable: T) where T: fmt::Display, { error!("{}", printable) } - /// ## logging at [`Level::Warn`] + /// ## logging at [`Level::WARN`] pub fn warn(&self, printable: T) where T: fmt::Display, { warn!("{}", printable) } - /// ## logging at [`Level::Info`] + /// ## logging at [`Level::INFO`] pub fn info(&self, printable: T) where T: fmt::Display, { info!("{}", printable) } - /// ## logging at [`Level::Debug`] + /// ## logging at [`Level::DEBUG`] pub fn debug(&self, printable: T) where T: fmt::Display, { debug!("{}", printable) } - /// ## logging at [`Level::Trace`] + /// ## logging at [`Level::TRACE`] pub fn trace(&self, printable: T) where T: fmt::Display, @@ -248,7 +238,7 @@ impl Logger { //////////////////////////////////////////////////////////////////////////////////////////////////// impl fmt::Debug for Logger { - /// ## Debug representation for [`Logger`] + /// ## DEBUG representation for [`Logger`] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!( f, diff --git a/members/pt-math/src/lib.rs b/members/pt-math/src/lib.rs index dac9d32..5a19879 100644 --- a/members/pt-math/src/lib.rs +++ b/members/pt-math/src/lib.rs @@ -1,12 +1,6 @@ -//! # very short description +//! # General Mathmatics functionalities //! -//! Short description -//! -//! Details -//! -//! ## Section 1 -//! -//! ## Section 2 +//! This module is currently empty, but will contain many math functionalities in a future version. //// ATTRIBUTES //////////////////////////////////////////////////////////////////////////////////// // we want docs