From 223a98569bb440572e0dbb05b9f85023fce6d22f Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Sun, 3 Aug 2025 13:36:00 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=92=A1=20Retoques=20menores=20en=20coment?= =?UTF-8?q?arios=20para=20documentar?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- helpers/pagetop-macros/src/lib.rs | 2 +- src/app.rs | 8 ++++---- src/base/component/html.rs | 10 +++++----- src/core/action.rs | 3 +-- src/core/component/definition.rs | 14 +++++++------- src/core/extension/definition.rs | 3 ++- src/core/theme/all.rs | 2 +- src/global.rs | 4 ++-- src/html/assets/favicon.rs | 4 ++-- src/html/assets/javascript.rs | 4 ++-- src/html/assets/stylesheet.rs | 4 ++-- src/html/context.rs | 6 +++--- src/locale.rs | 4 ++-- src/response/page.rs | 6 +++--- src/service.rs | 3 ++- 15 files changed, 39 insertions(+), 38 deletions(-) diff --git a/helpers/pagetop-macros/src/lib.rs b/helpers/pagetop-macros/src/lib.rs index 301f483..b9be0be 100644 --- a/helpers/pagetop-macros/src/lib.rs +++ b/helpers/pagetop-macros/src/lib.rs @@ -175,7 +175,7 @@ pub fn builder_fn(_: TokenStream, item: TokenStream) -> TokenStream { // Genera el método alter_...() con el código del método with_...(). let fn_alter_doc = format!( - "Igual que [`{0}()`](Self::{0}), pero sin usar el patrón *builder*.", + "Igual que [`Self::{0}()`](Self::{0}), pero sin usar el patrón *builder*.", fn_with_name_str, ); let fn_alter = quote! { diff --git a/src/app.rs b/src/app.rs index 6b11c0f..c3576fc 100644 --- a/src/app.rs +++ b/src/app.rs @@ -16,10 +16,10 @@ use std::sync::LazyLock; /// Punto de entrada de una aplicación `PageTop`. /// -/// No almacena datos, pero **encapsula** el ciclo completo de configuración y puesta en marcha. -/// Para instanciarla se puede usar [`new`](Application::new) o [`prepare`](Application::prepare). -/// Después sólo hay que llamar a [`run`](Application::run) (o a [`test`](Application::test) si se -/// está preparando un entorno de pruebas). +/// No almacena datos, **encapsula** el inicio completo de configuración y puesta en marcha. Para +/// instanciarla se puede usar [`new()`](Application::new) o [`prepare()`](Application::prepare). +/// Después sólo hay que llamar a [`run()`](Application::run) para ejecutar la aplicación (o a +/// [`test()`](Application::test) si se está preparando un entorno de pruebas). pub struct Application; impl Default for Application { diff --git a/src/base/component/html.rs b/src/base/component/html.rs index 1f49b05..8f273ed 100644 --- a/src/base/component/html.rs +++ b/src/base/component/html.rs @@ -51,9 +51,9 @@ impl Component for Html { impl Html { /// Crea una instancia que generará el `Markup`, con acceso opcional al contexto. /// - /// El método [`prepare_component`](crate::core::component::ComponentTrait::prepare_component) - /// delega el renderizado en la función proporcionada, que recibe una referencia mutable - /// al contexto de renderizado ([`Context`]). + /// El método [`prepare_component()`](crate::core::component::Component::prepare_component) + /// delega el renderizado en la función proporcionada, que recibe una referencia mutable al + /// contexto de renderizado ([`Context`]). pub fn with(f: F) -> Self where F: Fn(&mut Context) -> Markup + Send + Sync + 'static, @@ -64,8 +64,8 @@ impl Html { /// Sustituye la función que genera el `Markup`. /// /// Permite a otras extensiones modificar la función de renderizado que se ejecutará cuando - /// [`prepare_component`](crate::core::component::ComponentTrait::prepare_component) invoque - /// esta instancia. La nueva función también recibe una referencia al contexto ([`Context`]). + /// [`prepare_component()`](crate::core::component::Component::prepare_component) invoque esta + /// instancia. La nueva función también recibe una referencia al contexto ([`Context`]). pub fn alter_html(&mut self, f: F) -> &mut Self where F: Fn(&mut Context) -> Markup + Send + Sync + 'static, diff --git a/src/core/action.rs b/src/core/action.rs index 91847b0..cbbe79c 100644 --- a/src/core/action.rs +++ b/src/core/action.rs @@ -14,8 +14,7 @@ mod all; pub(crate) use all::add_action; pub use all::dispatch_actions; -/// Facilita la implementación del método -/// [`actions()`](crate::core::extension::ExtensionTrait::actions). +/// Facilita la implementación del método [`actions()`](crate::core::extension::Extension::actions). /// /// Evita escribir repetidamente `Box::new(...)` para cada acción de la lista, manteniendo el código /// más limpio. diff --git a/src/core/component/definition.rs b/src/core/component/definition.rs index e64e616..2818570 100644 --- a/src/core/component/definition.rs +++ b/src/core/component/definition.rs @@ -14,9 +14,9 @@ pub trait ComponentRender { /// Interfaz común que debe implementar un componente renderizable en `PageTop`. /// /// Se recomienda que los componentes deriven [`AutoDefault`](crate::AutoDefault). También deben -/// implementar explícitamente el método [`new`](Self::new) y pueden sobrescribir los otros métodos -/// para personalizar su comportamiento. -pub trait ComponentTrait: AnyInfo + ComponentRender + Send + Sync { +/// implementar explícitamente el método [`new()`](Self::new) y pueden sobrescribir los otros +/// métodos para personalizar su comportamiento. +pub trait Component: AnyInfo + ComponentRender + Send + Sync { /// Crea una nueva instancia del componente. fn new() -> Self where @@ -70,8 +70,8 @@ pub trait ComponentTrait: AnyInfo + ComponentRender + Send + Sync { /// /// 1. Despacha [`action::component::IsRenderable`](crate::base::action::component::IsRenderable) /// para ver si se puede renderizar. Si no es así, devuelve un [`Markup`] vacío. -/// 2. Ejecuta [`setup_before_prepare()`](ComponentTrait::setup_before_prepare) para que el -/// componente pueda ajustar su estructura interna o modificar el contexto. +/// 2. Ejecuta [`setup_before_prepare()`](Component::setup_before_prepare) para que el componente +/// pueda ajustar su estructura interna o modificar el contexto. /// 3. Despacha [`action::theme::BeforeRender`](crate::base::action::theme::BeforeRender) para /// que el tema pueda hacer ajustes en el componente o el contexto. /// 4. Despacha [`action::component::BeforeRender`](crate::base::action::component::BeforeRender) @@ -79,8 +79,8 @@ pub trait ComponentTrait: AnyInfo + ComponentRender + Send + Sync { /// 5. **Prepara el renderizado del componente**: /// - Despacha [`action::theme::PrepareRender`](crate::base::action::theme::PrepareRender) /// para permitir al tema preparar un renderizado diferente al predefinido. -/// - Si no es así, ejecuta [`prepare_component()`](ComponentTrait::prepare_component) para -/// preparar el renderizado predefinido del componente. +/// - Si no es así, ejecuta [`prepare_component()`](Component::prepare_component) para preparar +/// el renderizado predefinido del componente. /// 6. Despacha [`action::theme::AfterRender`](crate::base::action::theme::AfterRender) para /// que el tema pueda hacer sus últimos ajustes. /// 7. Despacha [`action::component::AfterRender`](crate::base::action::component::AfterRender) diff --git a/src/core/extension/definition.rs b/src/core/extension/definition.rs index 195e2e5..ac29259 100644 --- a/src/core/extension/definition.rs +++ b/src/core/extension/definition.rs @@ -28,7 +28,8 @@ pub type ExtensionRef = &'static dyn Extension; pub trait Extension: AnyInfo + Send + Sync { /// Nombre legible para el usuario. /// - /// Predeterminado por el [`short_name`](AnyInfo::short_name) del tipo asociado a la extensión. + /// Predeterminado por el [`short_name()`](AnyInfo::short_name) del tipo asociado a la + /// extensión. fn name(&self) -> L10n { L10n::n(self.short_name()) } diff --git a/src/core/theme/all.rs b/src/core/theme/all.rs index 787e0c9..ebb2848 100644 --- a/src/core/theme/all.rs +++ b/src/core/theme/all.rs @@ -19,7 +19,7 @@ pub static DEFAULT_THEME: LazyLock = // TEMA POR NOMBRE ********************************************************************************* -/// Devuelve el tema identificado por su [`short_name`](AnyInfo::short_name). +// Devuelve el tema identificado por su [`short_name()`](AnyInfo::short_name). pub fn theme_by_short_name(short_name: &'static str) -> Option { let short_name = short_name.to_lowercase(); match THEMES diff --git a/src/global.rs b/src/global.rs index 25a1781..ea659b8 100644 --- a/src/global.rs +++ b/src/global.rs @@ -53,8 +53,8 @@ pub struct App { /// Si no se especifica un valor válido, normalmente se usará el idioma devuelto por la /// implementación de [`LangId`](crate::locale::LangId) para [`Context`](crate::html::Context), /// en el siguiente orden: primero, el idioma establecido explícitamente con - /// [`Context::with_langid`](crate::html::Context::with_langid); si no se ha definido, se usará - /// el indicado en la cabecera `Accept-Language` del navegador; y, si ninguno aplica, se + /// [`Context::with_langid()`](crate::html::Context::with_langid); si no se ha definido, se + /// usará el indicado en la cabecera `Accept-Language` del navegador; y, si ninguno aplica, se /// empleará el idioma de respaldo ("en-US"). pub language: String, /// Banner ASCII mostrado al inicio: *"Off"* (desactivado), *"Slant"*, *"Small"*, *"Speed"* o diff --git a/src/html/assets/favicon.rs b/src/html/assets/favicon.rs index d02794e..2af0173 100644 --- a/src/html/assets/favicon.rs +++ b/src/html/assets/favicon.rs @@ -12,8 +12,8 @@ use crate::AutoDefault; /// /// > **Nota** /// > Los archivos de los iconos deben estar disponibles en el servidor web de la aplicación. Pueden -/// > incluirse en el proyecto utilizando [`include_files`](crate::include_files) y servirse con -/// > [`include_files_service`](crate::include_files_service). +/// > incluirse en el proyecto utilizando [`include_files!`](crate::include_files) y servirse con +/// > [`include_files_service!`](crate::include_files_service). /// /// # Ejemplo /// diff --git a/src/html/assets/javascript.rs b/src/html/assets/javascript.rs index 882b3af..604e85a 100644 --- a/src/html/assets/javascript.rs +++ b/src/html/assets/javascript.rs @@ -30,8 +30,8 @@ enum Source { /// /// > **Nota** /// > Los archivos de los *scripts* deben estar disponibles en el servidor web de la aplicación. -/// > Pueden incluirse en el proyecto utilizando [`include_files`](crate::include_files) y servirse -/// > con [`include_files_service`](crate::include_files_service). +/// > Pueden incluirse en el proyecto utilizando [`include_files!`](crate::include_files) y servirse +/// > con [`include_files_service!`](crate::include_files_service). /// /// # Ejemplo /// diff --git a/src/html/assets/stylesheet.rs b/src/html/assets/stylesheet.rs index dca5d86..72a79a1 100644 --- a/src/html/assets/stylesheet.rs +++ b/src/html/assets/stylesheet.rs @@ -55,8 +55,8 @@ impl TargetMedia { /// /// > **Nota** /// > Las hojas de estilo CSS deben estar disponibles en el servidor web de la aplicación. Pueden -/// > incluirse en el proyecto utilizando [`include_files`](crate::include_files) y servirse con -/// > [`include_files_service`](crate::include_files_service). +/// > incluirse en el proyecto utilizando [`include_files!`](crate::include_files) y servirse con +/// > [`include_files_service!`](crate::include_files_service). /// /// # Ejemplo /// diff --git a/src/html/context.rs b/src/html/context.rs index 8aaeb4a..5fbb39b 100644 --- a/src/html/context.rs +++ b/src/html/context.rs @@ -163,7 +163,7 @@ impl Context { /// Modifica el tema que se usará para renderizar el documento. /// - /// Localiza el tema por su [`short_name`](crate::core::AnyInfo::short_name), y si no aplica + /// Localiza el tema por su [`short_name()`](crate::core::AnyInfo::short_name), y si no aplica /// ninguno entonces usará el tema por defecto. #[builder_fn] pub fn with_theme(mut self, theme_name: &'static str) -> Self { @@ -301,8 +301,8 @@ impl Context { /// 4. Y si ninguna de las opciones anteriores aplica, se usa el idioma de respaldo (`"en-US"`). /// /// Resulta útil para usar un contexto ([`Context`]) como fuente de traducción en -/// [`L10n::using`](crate::locale::L10n::using) o -/// [`L10n::to_markup`](crate::locale::L10n::to_markup). +/// [`L10n::using()`](crate::locale::L10n::using) o +/// [`L10n::to_markup()`](crate::locale::L10n::to_markup). impl LangId for Context { fn langid(&self) -> &'static LanguageIdentifier { self.langid diff --git a/src/locale.rs b/src/locale.rs index d81243e..f23f51e 100644 --- a/src/locale.rs +++ b/src/locale.rs @@ -259,8 +259,8 @@ impl LangMatch { /// devuelve el idioma por defecto de la aplicación y, si tampoco está disponible, el idioma de /// respaldo ("en-US"). /// -/// Resulta útil para usar un valor de [`LangMatch`] como fuente de traducción en [`L10n::using`] o -/// [`L10n::to_markup`]. +/// Resulta útil para usar un valor de [`LangMatch`] como fuente de traducción en [`L10n::using()`] +/// o [`L10n::to_markup()`]. impl LangId for LangMatch { fn langid(&self) -> &'static LanguageIdentifier { match self { diff --git a/src/response/page.rs b/src/response/page.rs index 1b1c0de..44cab72 100644 --- a/src/response/page.rs +++ b/src/response/page.rs @@ -78,21 +78,21 @@ impl Page { self } - /// Modifica la fuente de idioma de la página ([`Context::with_langid`]). + /// Modifica la fuente de idioma de la página ([`Context::with_langid()`]). #[builder_fn] pub fn with_langid(mut self, language: &impl LangId) -> Self { self.context.alter_langid(language); self } - /// Modifica el tema que se usará para renderizar la página ([`Context::with_theme`]). + /// Modifica el tema que se usará para renderizar la página ([`Context::with_theme()`]). #[builder_fn] pub fn with_theme(mut self, theme_name: &'static str) -> Self { self.context.alter_theme(theme_name); self } - /// Modifica la composición para renderizar la página ([`Context::with_layout`]). + /// Modifica la composición para renderizar la página ([`Context::with_layout()`]). #[builder_fn] pub fn with_layout(mut self, layout_name: &'static str) -> Self { self.context.alter_layout(layout_name); diff --git a/src/service.rs b/src/service.rs index 261955c..89ba496 100644 --- a/src/service.rs +++ b/src/service.rs @@ -77,7 +77,8 @@ macro_rules! include_files { /// * `$route` – Ruta URL de origen desde la que se servirán los archivos. /// * `[ $root, $relative ]` *(opcional)* – Directorio raíz y ruta relativa para construir la ruta /// absoluta donde buscar los archivos en el sistema de ficheros (ver -/// [`absolute_dir`](crate::util::absolute_dir)). Si no existe, se usarán los recursos embebidos. +/// [`absolute_dir()`](crate::util::absolute_dir)). Si no existe, se usarán los recursos +/// embebidos. /// /// # Ejemplos ///