From 4d305a7ca4f6c5e26f646c5dde0564dd2afb4874 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Thu, 6 Jul 2023 18:30:01 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Revisi=C3=B3n=20de=20documentaci?= =?UTF-8?q?=C3=B3n=20y=20nomenclatura?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pagetop-homedemo/src/lib.rs | 48 ++++++++++++------------ pagetop/Cargo.toml | 6 +-- pagetop/src/config.rs | 74 ++++++++++++++++++------------------- pagetop/src/lib.rs | 3 +- 4 files changed, 64 insertions(+), 67 deletions(-) diff --git a/pagetop-homedemo/src/lib.rs b/pagetop-homedemo/src/lib.rs index 314917e9..f43f917b 100644 --- a/pagetop-homedemo/src/lib.rs +++ b/pagetop-homedemo/src/lib.rs @@ -1,9 +1,9 @@ use pagetop::prelude::*; use pagetop_minimal::component::*; -use_handle!(MODULE_DEMOHOME); +use_handle!(MODULE_HOMEDEMO); -use_locale!(LOCALE_DEMOHOME); +use_locale!(LOCALE_HOMEDEMO); use_static!(homedemo); @@ -11,15 +11,15 @@ pub struct HomeDemo; impl ModuleTrait for HomeDemo { fn handle(&self) -> Handle { - MODULE_DEMOHOME + MODULE_HOMEDEMO } fn name(&self) -> L10n { - L10n::t("module_name", &LOCALE_DEMOHOME) + L10n::t("module_name", &LOCALE_HOMEDEMO) } fn description(&self) -> L10n { - L10n::t("module_description", &LOCALE_DEMOHOME) + L10n::t("module_description", &LOCALE_HOMEDEMO) } fn dependencies(&self) -> Vec { @@ -34,7 +34,7 @@ impl ModuleTrait for HomeDemo { async fn demo(request: service::HttpRequest) -> ResultPage { Page::new(request) - .with_title(L10n::t("page_title", &LOCALE_DEMOHOME)) + .with_title(L10n::t("page_title", &LOCALE_HOMEDEMO)) .with_context(ContextOp::AddStyleSheet(StyleSheet::located( "/homedemo/css/styles.css", ))) @@ -55,11 +55,11 @@ fn hello_world() -> Container { .with_classes(ClassesOp::Add, "hello-col-text") .with_size(grid::ColumnSize::Is5of12) .with_component( - Heading::h1(L10n::t("page_title", &LOCALE_DEMOHOME)) + Heading::h1(L10n::t("page_title", &LOCALE_HOMEDEMO)) .with_display(HeadingDisplay::Medium), ) .with_component( - Paragraph::with(L10n::e("hello_intro", &LOCALE_DEMOHOME).with_arg( + Paragraph::with(L10n::e("hello_intro", &LOCALE_HOMEDEMO).with_arg( "app", format!( "{}", @@ -69,7 +69,7 @@ fn hello_world() -> Container { .with_display(ParagraphDisplay::Small), ) .with_component(Paragraph::with( - L10n::e("hello_powered", &LOCALE_DEMOHOME).with_arg( + L10n::e("hello_powered", &LOCALE_HOMEDEMO).with_arg( "pagetop", format!( "{}", @@ -80,14 +80,14 @@ fn hello_world() -> Container { .with_component( Anchor::button( "https://github.com/manuelcillero/pagetop", - L10n::t("hello_code", &LOCALE_DEMOHOME), + L10n::t("hello_code", &LOCALE_HOMEDEMO), ) .with_target(AnchorTarget::Blank) .with_left_icon(Icon::with("git")) .with_classes(ClassesOp::Add, "code-link"), ) .with_component( - Anchor::link("#welcome", L10n::t("hello_welcome", &LOCALE_DEMOHOME)) + Anchor::link("#welcome", L10n::t("hello_welcome", &LOCALE_HOMEDEMO)) .with_left_icon(Icon::with("arrow-down-circle-fill")) .with_classes(ClassesOp::Add, "welcome-link"), ), @@ -104,9 +104,9 @@ fn welcome() -> Container { Container::section() .with_id("welcome") .with_classes(ClassesOp::Add, "welcome-col-text") - .with_component(Heading::h2(L10n::t("welcome_page", &LOCALE_DEMOHOME))) + .with_component(Heading::h2(L10n::t("welcome_page", &LOCALE_HOMEDEMO))) .with_component( - Heading::h3(L10n::e("welcome_subtitle", &LOCALE_DEMOHOME).with_arg( + Heading::h3(L10n::e("welcome_subtitle", &LOCALE_HOMEDEMO).with_arg( "app", format!( "{}", @@ -116,10 +116,10 @@ fn welcome() -> Container { .with_display(HeadingDisplay::Subtitle), ) .with_component( - Paragraph::with(L10n::t("welcome_text1", &LOCALE_DEMOHOME)) + Paragraph::with(L10n::t("welcome_text1", &LOCALE_HOMEDEMO)) .with_display(ParagraphDisplay::Small), ) - .with_component(Paragraph::with(L10n::t("welcome_text2", &LOCALE_DEMOHOME))) + .with_component(Paragraph::with(L10n::t("welcome_text2", &LOCALE_HOMEDEMO))) } fn about_pagetop() -> Container { @@ -134,14 +134,14 @@ fn about_pagetop() -> Container { .with_column( grid::Column::new() .with_classes(ClassesOp::Add, "pagetop-col-text") - .with_component(Heading::h2(L10n::t("pagetop_title", &LOCALE_DEMOHOME))) + .with_component(Heading::h2(L10n::t("pagetop_title", &LOCALE_HOMEDEMO))) .with_component( - Paragraph::with(L10n::t("pagetop_text1", &LOCALE_DEMOHOME)) + Paragraph::with(L10n::t("pagetop_text1", &LOCALE_HOMEDEMO)) .with_display(ParagraphDisplay::Small), ) - .with_component(Paragraph::with(L10n::t("pagetop_text2", &LOCALE_DEMOHOME))) + .with_component(Paragraph::with(L10n::t("pagetop_text2", &LOCALE_HOMEDEMO))) .with_component(Paragraph::with( - L10n::e("pagetop_text3", &LOCALE_DEMOHOME) + L10n::e("pagetop_text3", &LOCALE_HOMEDEMO) .with_arg("href", "https://docs.rs/pagetop/latest/pagetop".to_string()), )), ), @@ -156,10 +156,10 @@ fn promo_pagetop() -> Container { .with_classes(ClassesOp::Add, "promo-col-text") .with_component(Heading::h2(L10n::t( "pagetop_promo_title", - &LOCALE_DEMOHOME, + &LOCALE_HOMEDEMO, ))) .with_component( - Paragraph::with(L10n::e("pagetop_promo_text1", &LOCALE_DEMOHOME).with_arg( + Paragraph::with(L10n::e("pagetop_promo_text1", &LOCALE_HOMEDEMO).with_arg( "pagetop", format!( "{}", @@ -192,15 +192,15 @@ fn reporting_issues() -> Container { .with_size(grid::ColumnSize::Is6of12) .with_component(Heading::h2(L10n::t( "report_problems_title", - &LOCALE_DEMOHOME, + &LOCALE_HOMEDEMO, ))) .with_component( - Paragraph::with(L10n::t("report_problems_text1", &LOCALE_DEMOHOME)) + Paragraph::with(L10n::t("report_problems_text1", &LOCALE_HOMEDEMO)) .with_display(ParagraphDisplay::Small), ) .with_component(Paragraph::with(L10n::t( "report_problems_text2", - &LOCALE_DEMOHOME, + &LOCALE_HOMEDEMO, ))), ), ) diff --git a/pagetop/Cargo.toml b/pagetop/Cargo.toml index 7b26e61e..db22d2f9 100644 --- a/pagetop/Cargo.toml +++ b/pagetop/Cargo.toml @@ -7,8 +7,9 @@ authors = [ "Manuel Cillero " ] description = """\ - PageTop is an opinionated web development framework that uses the most stable and popular Rust \ - packages to build modular, extensible and configurable Server-side rendered solutions.\ + PageTop is an opinionated web development framework that uses some of the most stable and \ + popular Rust packages to build modular, extensible and configurable Server-Side Rendering \ + (SSR) solutions. """ homepage = "https://pagetop.cillero.es" repository = "https://github.com/manuelcillero/pagetop" @@ -34,7 +35,6 @@ sqlite = ["database", "sea-orm/sqlx-sqlite"] [dependencies] async-trait = "0.1.68" concat-string = "1.0.1" -doc-comment = "0.3.3" figlet-rs = "0.1.5" itoa = "1.0.6" futures = "0.3.28" diff --git a/pagetop/src/config.rs b/pagetop/src/config.rs index 3f764c70..b3ee4a3b 100644 --- a/pagetop/src/config.rs +++ b/pagetop/src/config.rs @@ -1,4 +1,4 @@ -//! Lectura y uso de ajustes de configuración. +//! Read configuration files and use settings. //! //! Carga la configuración de la aplicación en forma de pares `clave = valor` recogidos en archivos //! [TOML](https://toml.io). @@ -51,15 +51,15 @@ //! serde = { version = "1.0", features = ["derive"] } //! ``` //! -//! Y luego declara con la macro [`use_config!`](crate::use_config) tus ajustes, usando tipos -//! seguros y asignando los valores predefinidos para la estructura asociada: +//! Y luego inicializa con la macro [`default_settings!`](crate::default_settings) tus ajustes, +//! usando tipos seguros y asignando los valores predefinidos para la estructura asociada: //! //! ``` //! use pagetop::prelude::*; //! use serde::Deserialize; //! //! #[derive(Debug, Deserialize)] -//! pub struct MySettings { +//! pub struct Settings { //! pub myapp: MyApp, //! } //! @@ -71,7 +71,7 @@ //! pub height: u16, //! } //! -//! use_config!(MY_SETTINGS as MySettings, +//! default_settings!( //! // [myapp] //! "myapp.name" => "Value Name", //! "myapp.width" => 900, @@ -106,8 +106,8 @@ //! } //! //! fn module_settings() { -//! println!("{} - {:?}", &MY_SETTINGS.myapp.name, &MY_SETTINGS.myapp.description); -//! println!("{}", &MY_SETTINGS.myapp.width); +//! println!("{} - {:?}", &SETTINGS.myapp.name, &SETTINGS.myapp.description); +//! println!("{}", &SETTINGS.myapp.width); //! } //! ``` @@ -164,30 +164,28 @@ pub static CONFIG: LazyStatic = LazyStatic::new(|| { /// Detiene la aplicación con un panic! si no pueden asignarse los ajustes de configuración. /// /// Ver [`Cómo añadir ajustes de configuración`](config/index.html#cómo-añadir-ajustes-de-configuración). -macro_rules! use_config { - ( $SETTINGS:ident as $Settings:ty $(, $key:literal => $value:literal)*$(,)* ) => { - $crate::doc_comment! { - concat!( - "Valores asignados o predefinidos para los ajustes de configuración globales ", - "asociados a la estructura [`", stringify!($Settings), "`]." - ), - pub static $SETTINGS: $crate::LazyStatic<$Settings> = $crate::LazyStatic::new(|| { - let mut settings = $crate::config::CONFIG.clone(); - $( - settings.set_default($key, $value).unwrap(); - )* - match settings.try_into() { - Ok(s) => s, - Err(e) => panic!("Error parsing settings: {}", e), - } - }); - } +macro_rules! default_settings { + ( $($key:literal => $value:literal),* $(,)? ) => { + #[doc = concat!( + "Assigned or predefined values for configuration settings associated with the ", + "[`Settings`] structure." + )] + pub static SETTINGS: $crate::LazyStatic = $crate::LazyStatic::new(|| { + let mut settings = $crate::config::CONFIG.clone(); + $( + settings.set_default($key, $value).unwrap(); + )* + match settings.try_into() { + Ok(s) => s, + Err(e) => panic!("Error parsing settings: {}", e), + } + }); }; } #[derive(Debug, Deserialize)] -/// Ajustes globales para las secciones reservadas [`[app]`](App), [`[database]`](Database), -/// [`[dev]`](Dev), [`[log]`](Log) y [`[server]`](Server) (ver [`SETTINGS`]). +/// Configuration settings for the [`[app]`](App), [`[database]`](Database), [`[dev]`](Dev), +/// [`[log]`](Log), and [`[server]`](Server) sections (see [`SETTINGS`]). pub struct Settings { pub app: App, pub database: Database, @@ -197,9 +195,9 @@ pub struct Settings { } #[derive(Debug, Deserialize)] -/// Sección `[app]` de los ajustes de configuración globales. +/// Section `[app]` of the configuration settings. /// -/// Ver [`Settings`]. +/// See [`Settings`]. pub struct App { /// El nombre de la aplicación. /// Por defecto: *"PageTop App"*. @@ -225,9 +223,9 @@ pub struct App { } #[derive(Debug, Deserialize)] -/// Sección `[database]` de los ajustes de configuración globales. +/// Section `[database]` of the configuration settings. /// -/// Ver [`Settings`]. +/// See [`Settings`]. pub struct Database { /// Tipo de base de datos: *"mysql"*, *"postgres"* ó *"sqlite"*. /// Por defecto: *""*. @@ -253,9 +251,9 @@ pub struct Database { } #[derive(Debug, Deserialize)] -/// Sección `[dev]` de los ajustes de configuración globales. +/// Section `[dev]` of the configuration settings. /// -/// Ver [`Settings`]. +/// See [`Settings`]. pub struct Dev { /// Los archivos estáticos requeridos por la aplicación se integran de manera predeterminada en /// el binario ejecutable. Sin embargo, durante el desarrollo puede resultar útil servir estos @@ -266,9 +264,9 @@ pub struct Dev { } #[derive(Debug, Deserialize)] -/// Sección `[log]` de los ajustes de configuración globales. +/// Section `[log]` of the configuration settings. /// -/// Ver [`Settings`]. +/// See [`Settings`]. pub struct Log { /// Filtro, o combinación de filtros separados por coma, para la traza de ejecución: *"Error"*, /// *"Warn"*, *"Info"*, *"Debug"* o *"Trace"*. @@ -291,9 +289,9 @@ pub struct Log { } #[derive(Debug, Deserialize)] -/// Sección `[server]` de los ajustes de configuración globales. +/// Section `[server]` of the configuration settings. /// -/// Ver [`Settings`]. +/// See [`Settings`]. pub struct Server { /// Dirección del servidor web. /// Por defecto: *"localhost"*. @@ -306,7 +304,7 @@ pub struct Server { pub session_lifetime: i64, } -use_config!(SETTINGS as Settings, +default_settings!( // [app] "app.name" => "PageTop App", "app.description" => "Modular web solutions made simple with PageTop.", diff --git a/pagetop/src/lib.rs b/pagetop/src/lib.rs index 91b9dbda..76a8134a 100644 --- a/pagetop/src/lib.rs +++ b/pagetop/src/lib.rs @@ -69,7 +69,7 @@ //! } //! ``` //! Este programa crea un módulo llamado `HelloWorld` con un servicio que devuelve una página web -//! saludando al mundo cada vez que se accede desde el navegador a `http://localhost:8088` (según +//! saludando al mundo cada vez que se accede desde el navegador a `http://localhost:8088` (para //! los [ajustes de configuración](`config::Server`) predeterminados). //! //! # 🧱 Extendiendo PageTop @@ -102,7 +102,6 @@ // ************************************************************************************************* pub use concat_string::concat_string; -pub use doc_comment::doc_comment; pub use once_cell::sync::Lazy as LazyStatic; pub use paste::paste; pub use static_files::Resource as StaticResource;