manuelcillero/pagetop
manuelcillero/pagetop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

💡 Mejora legibilidad de comentarios

Browse source
This commit is contained in:
Manuel Cillero 2025-09-28 08:51:21 +02:00
parent f5290b477f
commit f5fb4b7a1d
21 changed files with 74 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

6
src/base/component/block.rs
View file

@ -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 {

4
src/base/component/html.rs
View file

@ -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.
///

4
src/base/component/poweredby.rs
View file

@ -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> {

6
src/core/action/all.rs
View file

@ -5,12 +5,12 @@ use parking_lot::RwLock;
use std::collections::HashMap;
use std::sync::LazyLock;
// ACCIONES ****************************************************************************************
// **< ACCIONES >***********************************************************************************
static ACTIONS: LazyLock<RwLock<HashMap<ActionKey, ActionsList>>> =
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`].
///

24
src/core/component/children.rs
View file

@ -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<C: Component> Typed<C> {
Typed(Some(Arc::new(RwLock::new(component))))
}
// Typed BUILDER *******************************************************************************
// **< Typed BUILDER >**************************************************************************
/// Establece un componente nuevo, o lo vacía.
///
@ -85,7 +85,7 @@ impl<C: Component> Typed<C> {
self
}
// Typed GETTERS *******************************************************************************
// **< Typed GETTERS >**************************************************************************
/// Devuelve el identificador del componente, si existe y está definido.
#[inline]
@ -93,14 +93,14 @@ impl<C: Component> Typed<C> {
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]

10
src/core/extension/all.rs
View file

@ -7,7 +7,7 @@ use parking_lot::RwLock;
use std::sync::LazyLock;
// EXTENSIONES *************************************************************************************
// **< EXTENSIONES >********************************************************************************
static ENABLED_EXTENSIONS: LazyLock<RwLock<Vec<ExtensionRef>>> =
LazyLock::new(|| RwLock::new(Vec::new()));
@ -15,7 +15,7 @@ static ENABLED_EXTENSIONS: LazyLock<RwLock<Vec<ExtensionRef>>> =
static DROPPED_EXTENSIONS: LazyLock<RwLock<Vec<ExtensionRef>>> =
LazyLock::new(|| RwLock::new(Vec::new()));
// REGISTRO DE LAS EXTENSIONES *********************************************************************
// **< REGISTRO DE LAS EXTENSIONES >****************************************************************
pub fn register_extensions(root_extension: Option<ExtensionRef>) {
// Prepara la lista de extensiones habilitadas.
@ -104,7 +104,7 @@ fn add_to_dropped(list: &mut Vec<ExtensionRef>, 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.

6
src/core/theme/all.rs
View file

@ -5,11 +5,11 @@ use parking_lot::RwLock;
use std::sync::LazyLock;
// TEMAS *******************************************************************************************
// **< TEMAS >**************************************************************************************
pub static THEMES: LazyLock<RwLock<Vec<ThemeRef>>> = LazyLock::new(|| RwLock::new(Vec::new()));
// TEMA PREDETERMINADO *****************************************************************************
// **< TEMA PREDETERMINADO >************************************************************************
pub static DEFAULT_THEME: LazyLock<ThemeRef> =
LazyLock::new(|| match theme_by_short_name(&global::SETTINGS.app.theme) {
@ -17,7 +17,7 @@ pub static DEFAULT_THEME: LazyLock<ThemeRef> =
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<ThemeRef> {

6
src/html.rs
View file

@ -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;

4
src/html/assets/favicon.rs
View file

@ -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

4
src/html/assets/javascript.rs
View file

@ -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! {

6
src/html/assets/stylesheet.rs
View file

@ -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! {

4
src/html/attr_classes.rs
View file

@ -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<str>) -> Self {
@ -114,7 +114,7 @@ impl AttrClasses {
}
}
// AttrClasses GETTERS *************************************************************************
// **< AttrClasses GETTERS >********************************************************************
/// Devuelve la cadena de clases, si existe.
pub fn get(&self) -> Option<String> {

4
src/html/attr_id.rs
View file

@ -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<String> {

4
src/html/attr_l10n.rs
View file

@ -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<String> {

4
src/html/attr_name.rs
View file

@ -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<String> {

4
src/html/attr_value.rs
View file

@ -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<String> {

16
src/html/context.rs
View file

@ -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<JavaScript>;
// Contextual HELPERS **************************************************************************
// **< Contextual HELPERS >*********************************************************************
/// Genera un identificador único por tipo (`<tipo>-<n>`) 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<HttpRequest>) -> 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.

6
src/lib.rs
View file

@ -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;

12
src/response/page.rs
View file

@ -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<String> {
@ -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<HttpRequest>) -> 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<T>(&mut self, id: Option<String>) -> String {
self.context.required_id::<T>(id)

6
src/util.rs
View file

@ -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.
///