From f5fb4b7a1d5216d43cdbb86fd70cb0f4e724488b Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Sun, 28 Sep 2025 08:51:21 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=92=A1=20Mejora=20legibilidad=20de=20come?= =?UTF-8?q?ntarios?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/base/component/block.rs | 6 +++--- src/base/component/html.rs | 4 ++-- src/base/component/poweredby.rs | 4 ++-- src/core/action/all.rs | 6 +++--- src/core/component/children.rs | 24 ++++++++++++------------ src/core/extension/all.rs | 10 +++++----- src/core/theme/all.rs | 6 +++--- src/html.rs | 6 +++--- src/html/assets/favicon.rs | 4 +++- src/html/assets/javascript.rs | 4 +++- src/html/assets/stylesheet.rs | 6 ++++-- src/html/attr_classes.rs | 4 ++-- src/html/attr_id.rs | 4 ++-- src/html/attr_l10n.rs | 4 ++-- src/html/attr_name.rs | 4 ++-- src/html/attr_value.rs | 4 ++-- src/html/context.rs | 16 ++++++++-------- src/lib.rs | 6 +++--- src/response/page.rs | 12 ++++++------ src/util.rs | 6 +++--- tests/component_poweredby.rs | 2 +- 21 files changed, 74 insertions(+), 68 deletions(-) diff --git a/src/base/component/block.rs b/src/base/component/block.rs index c96f2ba..9a04c4e 100644 --- a/src/base/component/block.rs +++ b/src/base/component/block.rs @@ -47,7 +47,7 @@ impl Component for Block { } impl Block { - // Block BUILDER ******************************************************************************* + // **< Block BUILDER >************************************************************************** /// Establece el identificador único (`id`) del bloque. #[builder_fn] @@ -77,14 +77,14 @@ impl Block { self } - /// Modifica la lista de hijos (`children`) aplicando una operación. + /// Modifica la lista de hijos (`children`) aplicando una operación [`ChildOp`]. #[builder_fn] pub fn with_child(mut self, op: ChildOp) -> Self { self.children.alter_child(op); self } - // Block GETTERS ******************************************************************************* + // **< Block GETTERS >************************************************************************** /// Devuelve las clases CSS asociadas al bloque. pub fn classes(&self) -> &AttrClasses { diff --git a/src/base/component/html.rs b/src/base/component/html.rs index 8fa5690..b8c4aaa 100644 --- a/src/base/component/html.rs +++ b/src/base/component/html.rs @@ -49,7 +49,7 @@ impl Component for Html { } impl Html { - // Html BUILDER ******************************************************************************** + // **< Html BUILDER >*************************************************************************** /// Crea una instancia que generará el `Markup`, con acceso opcional al contexto. /// @@ -77,7 +77,7 @@ impl Html { self } - // Html GETTERS ******************************************************************************** + // **< Html GETTERS >*************************************************************************** /// Aplica la función interna de renderizado con el [`Context`] proporcionado. /// diff --git a/src/base/component/poweredby.rs b/src/base/component/poweredby.rs index bfe3835..4b54af3 100644 --- a/src/base/component/poweredby.rs +++ b/src/base/component/poweredby.rs @@ -39,7 +39,7 @@ impl Component for PoweredBy { } impl PoweredBy { - // PoweredBy BUILDER *************************************************************************** + // **< PoweredBy BUILDER >********************************************************************** /// Establece el texto de copyright que mostrará el componente. /// @@ -58,7 +58,7 @@ impl PoweredBy { self } - // PoweredBy GETTERS *************************************************************************** + // **< PoweredBy GETTERS >********************************************************************** /// Devuelve el texto de copyright actual, si existe. pub fn copyright(&self) -> Option<&str> { diff --git a/src/core/action/all.rs b/src/core/action/all.rs index 7fff970..fbbf842 100644 --- a/src/core/action/all.rs +++ b/src/core/action/all.rs @@ -5,12 +5,12 @@ use parking_lot::RwLock; use std::collections::HashMap; use std::sync::LazyLock; -// ACCIONES **************************************************************************************** +// **< ACCIONES >*********************************************************************************** static ACTIONS: LazyLock>> = LazyLock::new(|| RwLock::new(HashMap::new())); -// AÑADIR ACCIONES ********************************************************************************* +// **< AÑADIR ACCIONES >**************************************************************************** // Registra una nueva acción en el sistema. // @@ -36,7 +36,7 @@ pub fn add_action(action: ActionBox) { } } -// DESPLEGAR ACCIONES ****************************************************************************** +// **< DESPLEGAR ACCIONES >************************************************************************* /// Despacha y ejecuta las funciones asociadas a una [`ActionKey`]. /// diff --git a/src/core/component/children.rs b/src/core/component/children.rs index 2b16f06..920dacf 100644 --- a/src/core/component/children.rs +++ b/src/core/component/children.rs @@ -20,7 +20,7 @@ impl Child { Child(Some(Arc::new(RwLock::new(component)))) } - // Child BUILDER ******************************************************************************* + // **< Child BUILDER >************************************************************************** /// Establece un componente nuevo, o lo vacía. /// @@ -35,7 +35,7 @@ impl Child { self } - // Child GETTERS ******************************************************************************* + // **< Child GETTERS >************************************************************************** /// Devuelve el identificador del componente, si existe y está definido. #[inline] @@ -43,14 +43,14 @@ impl Child { self.0.as_ref().and_then(|c| c.read().id()) } - // Child RENDER ******************************************************************************** + // **< Child RENDER >*************************************************************************** /// Renderiza el componente con el contexto proporcionado. pub fn render(&self, cx: &mut Context) -> Markup { self.0.as_ref().map_or(html! {}, |c| c.write().render(cx)) } - // Child HELPERS ******************************************************************************* + // **< Child HELPERS >************************************************************************** // Devuelve el [`UniqueId`] del tipo del componente, si existe. #[inline] @@ -74,7 +74,7 @@ impl Typed { Typed(Some(Arc::new(RwLock::new(component)))) } - // Typed BUILDER ******************************************************************************* + // **< Typed BUILDER >************************************************************************** /// Establece un componente nuevo, o lo vacía. /// @@ -85,7 +85,7 @@ impl Typed { self } - // Typed GETTERS ******************************************************************************* + // **< Typed GETTERS >************************************************************************** /// Devuelve el identificador del componente, si existe y está definido. #[inline] @@ -93,14 +93,14 @@ impl Typed { self.0.as_ref().and_then(|c| c.read().id()) } - // Typed RENDER ******************************************************************************** + // **< Typed RENDER >*************************************************************************** /// Renderiza el componente con el contexto proporcionado. pub fn render(&self, cx: &mut Context) -> Markup { self.0.as_ref().map_or(html! {}, |c| c.write().render(cx)) } - // Typed HELPERS ******************************************************************************* + // **< Typed HELPERS >************************************************************************** // Convierte el componente tipado en un [`Child`]. #[inline] @@ -165,7 +165,7 @@ impl Children { opt } - // Children BUILDER **************************************************************************** + // **< Children BUILDER >*********************************************************************** /// Ejecuta una operación con [`ChildOp`] en la lista. #[builder_fn] @@ -204,7 +204,7 @@ impl Children { self } - // Children GETTERS **************************************************************************** + // **< Children GETTERS >*********************************************************************** /// Devuelve el número de componentes hijo de la lista. pub fn len(&self) -> usize { @@ -233,7 +233,7 @@ impl Children { self.0.iter().filter(move |&c| c.type_id() == Some(type_id)) } - // Children RENDER ***************************************************************************** + // **< Children RENDER >************************************************************************ /// Renderiza todos los componentes hijo, en orden. pub fn render(&self, cx: &mut Context) -> Markup { @@ -244,7 +244,7 @@ impl Children { } } - // Children HELPERS **************************************************************************** + // **< Children HELPERS >*********************************************************************** // Inserta un hijo después del componente con el `id` dado, o al final si no se encuentra. #[inline] diff --git a/src/core/extension/all.rs b/src/core/extension/all.rs index a243778..fa67671 100644 --- a/src/core/extension/all.rs +++ b/src/core/extension/all.rs @@ -7,7 +7,7 @@ use parking_lot::RwLock; use std::sync::LazyLock; -// EXTENSIONES ************************************************************************************* +// **< EXTENSIONES >******************************************************************************** static ENABLED_EXTENSIONS: LazyLock>> = LazyLock::new(|| RwLock::new(Vec::new())); @@ -15,7 +15,7 @@ static ENABLED_EXTENSIONS: LazyLock>> = static DROPPED_EXTENSIONS: LazyLock>> = LazyLock::new(|| RwLock::new(Vec::new())); -// REGISTRO DE LAS EXTENSIONES ********************************************************************* +// **< REGISTRO DE LAS EXTENSIONES >**************************************************************** pub fn register_extensions(root_extension: Option) { // Prepara la lista de extensiones habilitadas. @@ -104,7 +104,7 @@ fn add_to_dropped(list: &mut Vec, extension: ExtensionRef) { } } -// REGISTRO DE LAS ACCIONES ************************************************************************ +// **< REGISTRO DE LAS ACCIONES >******************************************************************* pub fn register_actions() { for extension in ENABLED_EXTENSIONS.read().iter() { @@ -114,7 +114,7 @@ pub fn register_actions() { } } -// INICIALIZA LAS EXTENSIONES ********************************************************************** +// **< INICIALIZA LAS EXTENSIONES >***************************************************************** pub fn initialize_extensions() { trace::info!("Calling application bootstrap"); @@ -123,7 +123,7 @@ pub fn initialize_extensions() { } } -// CONFIGURA LOS SERVICIOS ************************************************************************* +// **< CONFIGURA LOS SERVICIOS >******************************************************************** pub fn configure_services(scfg: &mut service::web::ServiceConfig) { // Sólo compila durante el desarrollo, para evitar errores 400 en la traza de eventos. diff --git a/src/core/theme/all.rs b/src/core/theme/all.rs index ebb2848..5e6b65b 100644 --- a/src/core/theme/all.rs +++ b/src/core/theme/all.rs @@ -5,11 +5,11 @@ use parking_lot::RwLock; use std::sync::LazyLock; -// TEMAS ******************************************************************************************* +// **< TEMAS >************************************************************************************** pub static THEMES: LazyLock>> = LazyLock::new(|| RwLock::new(Vec::new())); -// TEMA PREDETERMINADO ***************************************************************************** +// **< TEMA PREDETERMINADO >************************************************************************ pub static DEFAULT_THEME: LazyLock = LazyLock::new(|| match theme_by_short_name(&global::SETTINGS.app.theme) { @@ -17,7 +17,7 @@ pub static DEFAULT_THEME: LazyLock = None => &crate::base::theme::Basic, }); -// TEMA POR NOMBRE ********************************************************************************* +// **< TEMA POR NOMBRE >**************************************************************************** // Devuelve el tema identificado por su [`short_name()`](AnyInfo::short_name). pub fn theme_by_short_name(short_name: &'static str) -> Option { diff --git a/src/html.rs b/src/html.rs index 4a965ca..b6815ec 100644 --- a/src/html.rs +++ b/src/html.rs @@ -3,7 +3,7 @@ mod maud; pub use maud::{display, html, html_private, Escaper, Markup, PreEscaped, DOCTYPE}; -// HTML DOCUMENT ASSETS **************************************************************************** +// **< HTML DOCUMENT ASSETS >*********************************************************************** mod assets; pub use assets::favicon::Favicon; @@ -11,12 +11,12 @@ pub use assets::javascript::JavaScript; pub use assets::stylesheet::{StyleSheet, TargetMedia}; pub use assets::{Asset, Assets}; -// HTML DOCUMENT CONTEXT *************************************************************************** +// **< HTML DOCUMENT CONTEXT >********************************************************************** mod context; pub use context::{AssetsOp, Context, Contextual, ErrorParam}; -// HTML ATTRIBUTES ********************************************************************************* +// **< HTML ATTRIBUTES >**************************************************************************** mod attr_id; pub use attr_id::AttrId; diff --git a/src/html/assets/favicon.rs b/src/html/assets/favicon.rs index d731b8f..56c3905 100644 --- a/src/html/assets/favicon.rs +++ b/src/html/assets/favicon.rs @@ -52,7 +52,7 @@ impl Favicon { Favicon::default() } - // Favicon BUILDER ***************************************************************************** + // **< Favicon BUILDER >************************************************************************ /// Le añade un icono genérico apuntando a `image`. El tipo MIME se infiere automáticamente a /// partir de la extensión. @@ -152,6 +152,8 @@ impl Favicon { self } + // **< Favicon RENDER >************************************************************************* + /// Renderiza el **Favicon** completo con todas las etiquetas declaradas. /// /// El parámetro `Context` se acepta por coherencia con el resto de *assets*, aunque en este diff --git a/src/html/assets/javascript.rs b/src/html/assets/javascript.rs index a8ed3e8..4649cdb 100644 --- a/src/html/assets/javascript.rs +++ b/src/html/assets/javascript.rs @@ -171,7 +171,7 @@ impl JavaScript { } } - // JavaScript BUILDER ************************************************************************** + // **< JavaScript BUILDER >********************************************************************* /// Asocia una **versión** al recurso (usada para control de la caché del navegador). /// @@ -210,6 +210,8 @@ impl Asset for JavaScript { self.weight } + // **< JavaScript RENDER >********************************************************************** + fn render(&self, cx: &mut Context) -> Markup { match &self.source { Source::From(path) => html! { diff --git a/src/html/assets/stylesheet.rs b/src/html/assets/stylesheet.rs index 3ecc77f..b54f4cf 100644 --- a/src/html/assets/stylesheet.rs +++ b/src/html/assets/stylesheet.rs @@ -113,7 +113,7 @@ impl StyleSheet { } } - // StyleSheet BUILDER ************************************************************************** + // **< StyleSheet BUILDER >********************************************************************* /// Asocia una versión al recurso (usada para control de la caché del navegador). /// @@ -132,7 +132,7 @@ impl StyleSheet { self } - // StyleSheet EXTRAS *************************************************************************** + // **< StyleSheet HELPERS >********************************************************************* /// Especifica el medio donde se aplican los estilos. /// @@ -163,6 +163,8 @@ impl Asset for StyleSheet { self.weight } + // **< StyleSheet RENDER >********************************************************************** + fn render(&self, cx: &mut Context) -> Markup { match &self.source { Source::From(path) => html! { diff --git a/src/html/attr_classes.rs b/src/html/attr_classes.rs index 098c26c..80fdad7 100644 --- a/src/html/attr_classes.rs +++ b/src/html/attr_classes.rs @@ -48,7 +48,7 @@ impl AttrClasses { AttrClasses::default().with_value(ClassesOp::Prepend, classes) } - // AttrClasses BUILDER ************************************************************************* + // **< AttrClasses BUILDER >******************************************************************** #[builder_fn] pub fn with_value(mut self, op: ClassesOp, classes: impl AsRef) -> Self { @@ -114,7 +114,7 @@ impl AttrClasses { } } - // AttrClasses GETTERS ************************************************************************* + // **< AttrClasses GETTERS >******************************************************************** /// Devuelve la cadena de clases, si existe. pub fn get(&self) -> Option { diff --git a/src/html/attr_id.rs b/src/html/attr_id.rs index 8bb1d33..3d5f3eb 100644 --- a/src/html/attr_id.rs +++ b/src/html/attr_id.rs @@ -29,7 +29,7 @@ impl AttrId { AttrId::default().with_value(value) } - // AttrId BUILDER ****************************************************************************** + // **< AttrId BUILDER >************************************************************************* /// Establece un identificador nuevo normalizando el valor. #[builder_fn] @@ -39,7 +39,7 @@ impl AttrId { self } - // AttrId GETTERS ****************************************************************************** + // **< AttrId GETTERS >************************************************************************* /// Devuelve el identificador normalizado, si existe. pub fn get(&self) -> Option { diff --git a/src/html/attr_l10n.rs b/src/html/attr_l10n.rs index 8250c74..37fc80f 100644 --- a/src/html/attr_l10n.rs +++ b/src/html/attr_l10n.rs @@ -39,7 +39,7 @@ impl AttrL10n { AttrL10n(value) } - // AttrL10n BUILDER **************************************************************************** + // **< AttrL10n BUILDER >*********************************************************************** /// Establece una traducción nueva. #[builder_fn] @@ -48,7 +48,7 @@ impl AttrL10n { self } - // AttrL10n GETTERS **************************************************************************** + // **< AttrL10n GETTERS >*********************************************************************** /// Devuelve la traducción para `language`, si existe. pub fn lookup(&self, language: &impl LangId) -> Option { diff --git a/src/html/attr_name.rs b/src/html/attr_name.rs index 928f841..9bc9659 100644 --- a/src/html/attr_name.rs +++ b/src/html/attr_name.rs @@ -29,7 +29,7 @@ impl AttrName { AttrName::default().with_value(value) } - // AttrName BUILDER **************************************************************************** + // **< AttrName BUILDER >*********************************************************************** /// Establece un nombre nuevo normalizando el valor. #[builder_fn] @@ -39,7 +39,7 @@ impl AttrName { self } - // AttrName GETTERS **************************************************************************** + // **< AttrName GETTERS >*********************************************************************** /// Devuelve el nombre normalizado, si existe. pub fn get(&self) -> Option { diff --git a/src/html/attr_value.rs b/src/html/attr_value.rs index 4e03120..eff8066 100644 --- a/src/html/attr_value.rs +++ b/src/html/attr_value.rs @@ -27,7 +27,7 @@ impl AttrValue { AttrValue::default().with_value(value) } - // AttrValue BUILDER *************************************************************************** + // **< AttrValue BUILDER >********************************************************************** /// Establece una cadena nueva normalizando el valor. #[builder_fn] @@ -41,7 +41,7 @@ impl AttrValue { self } - // AttrValue GETTERS *************************************************************************** + // **< AttrValue GETTERS >********************************************************************** /// Devuelve la cadena normalizada, si existe. pub fn get(&self) -> Option { diff --git a/src/html/context.rs b/src/html/context.rs index 7b78268..355ccea 100644 --- a/src/html/context.rs +++ b/src/html/context.rs @@ -78,7 +78,7 @@ pub enum ErrorParam { /// } /// ``` pub trait Contextual: LangId { - // Contextual BUILDER ************************************************************************** + // **< Contextual BUILDER >********************************************************************* /// Establece el idioma del documento. #[builder_fn] @@ -104,7 +104,7 @@ pub trait Contextual: LangId { #[builder_fn] fn with_assets(self, op: AssetsOp) -> Self; - // Contextual GETTERS ************************************************************************** + // **< Contextual GETTERS >********************************************************************* /// Devuelve una referencia a la solicitud HTTP asociada, si existe. fn request(&self) -> Option<&HttpRequest>; @@ -142,7 +142,7 @@ pub trait Contextual: LangId { /// Devuelve los scripts JavaScript de los recursos del contexto. fn javascripts(&self) -> &Assets; - // Contextual HELPERS ************************************************************************** + // **< Contextual HELPERS >********************************************************************* /// Genera un identificador único por tipo (`-`) cuando no se aporta uno explícito. /// @@ -255,7 +255,7 @@ impl Context { } } - // Context RENDER ****************************************************************************** + // **< Context RENDER >************************************************************************* /// Renderiza los recursos del contexto. pub fn render_assets(&mut self) -> Markup { @@ -283,7 +283,7 @@ impl Context { markup } - // Context PARAMS ****************************************************************************** + // **< Context PARAMS >************************************************************************* /// Recupera una *referencia tipada* al parámetro solicitado. /// @@ -389,7 +389,7 @@ impl LangId for Context { } impl Contextual for Context { - // Contextual BUILDER ************************************************************************** + // **< Contextual BUILDER >********************************************************************* #[builder_fn] fn with_request(mut self, request: Option) -> Self { @@ -471,7 +471,7 @@ impl Contextual for Context { self } - // Contextual GETTERS ************************************************************************** + // **< Contextual GETTERS >********************************************************************* fn request(&self) -> Option<&HttpRequest> { self.request.as_ref() @@ -530,7 +530,7 @@ impl Contextual for Context { &self.javascripts } - // Contextual HELPERS ************************************************************************** + // **< Contextual HELPERS >********************************************************************* /// Devuelve un identificador único dentro del contexto para el tipo `T`, si no se proporciona /// un `id` explícito. diff --git a/src/lib.rs b/src/lib.rs index 1c1ba2c..6f5c5cf 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -97,7 +97,7 @@ extern crate self as pagetop; use std::collections::HashMap; use std::ops::Deref; -// RE-EXPORTED ************************************************************************************* +// **< RE-EXPORTED >******************************************************************************** pub use pagetop_macros::{builder_fn, html, main, test, AutoDefault}; @@ -136,7 +136,7 @@ pub type UniqueId = std::any::TypeId; /// antes en la ordenación. pub type Weight = i8; -// API ********************************************************************************************* +// **< API >**************************************************************************************** // Macros y funciones útiles. pub mod util; @@ -163,6 +163,6 @@ pub mod base; // Prepara y ejecuta la aplicación. pub mod app; -// PRELUDE ***************************************************************************************** +// **< PRELUDE >************************************************************************************ pub mod prelude; diff --git a/src/response/page.rs b/src/response/page.rs index 2dc27f9..e9d3067 100644 --- a/src/response/page.rs +++ b/src/response/page.rs @@ -52,7 +52,7 @@ impl Page { } } - // Page BUILDER ******************************************************************************** + // **< Page BUILDER >*************************************************************************** /// Establece el título de la página como un valor traducible. #[builder_fn] @@ -151,7 +151,7 @@ impl Page { self } - // Page GETTERS ******************************************************************************** + // **< Page GETTERS >*************************************************************************** /// Devuelve el título traducido para el idioma de la página, si existe. pub fn title(&mut self) -> Option { @@ -192,7 +192,7 @@ impl Page { &mut self.context } - // Page RENDER ********************************************************************************* + // **< Page RENDER >**************************************************************************** /// Renderiza los componentes de una región (`region_name`) de la página. pub fn render_region(&mut self, region_name: &'static str) -> Markup { @@ -253,7 +253,7 @@ impl LangId for Page { } impl Contextual for Page { - // Contextual BUILDER ************************************************************************** + // **< Contextual BUILDER >********************************************************************* #[builder_fn] fn with_request(mut self, request: Option) -> Self { @@ -291,7 +291,7 @@ impl Contextual for Page { self } - // Contextual GETTERS ************************************************************************** + // **< Contextual GETTERS >********************************************************************* fn request(&self) -> Option<&HttpRequest> { self.context.request() @@ -321,7 +321,7 @@ impl Contextual for Page { self.context.javascripts() } - // Contextual HELPERS ************************************************************************** + // **< Contextual HELPERS >********************************************************************* fn required_id(&mut self, id: Option) -> String { self.context.required_id::(id) diff --git a/src/util.rs b/src/util.rs index cb10176..a4daf67 100644 --- a/src/util.rs +++ b/src/util.rs @@ -6,7 +6,7 @@ use std::env; use std::io; use std::path::{Path, PathBuf}; -// MACROS INTEGRADAS ******************************************************************************* +// **< MACROS INTEGRADAS >************************************************************************** #[doc(hidden)] pub use paste::paste; @@ -16,7 +16,7 @@ pub use concat_string::concat_string; pub use indoc::{concatdoc, formatdoc, indoc}; -// MACROS ÚTILES *********************************************************************************** +// **< MACROS ÚTILES >****************************************************************************** #[macro_export] /// Macro para construir una colección de pares clave-valor. @@ -198,7 +198,7 @@ macro_rules! join_strict { }}; } -// FUNCIONES ÚTILES ******************************************************************************** +// **< FUNCIONES ÚTILES >*************************************************************************** /// Resuelve y valida la ruta de un directorio existente, devolviendo una ruta absoluta. /// diff --git a/tests/component_poweredby.rs b/tests/component_poweredby.rs index e4551d1..27683d9 100644 --- a/tests/component_poweredby.rs +++ b/tests/component_poweredby.rs @@ -90,7 +90,7 @@ async fn poweredby_getter_reflects_internal_state() { assert!(c1.contains(&global::SETTINGS.app.name)); } -// HELPERS ***************************************************************************************** +// **< HELPERS >************************************************************************************ fn render_component(c: &C) -> Markup { let mut cx = Context::default();