💡 Retoques menores en comentarios para documentar

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

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.
+/// No almacena datos, **encapsula** el inicio completo de configuración y puesta en marcha. Para
-/// Para instanciarla se puede usar [`new`](Application::new) o [`prepare`](Application::prepare).
+/// 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
+/// Después sólo hay que llamar a [`run()`](Application::run) para ejecutar la aplicación (o a
-/// está preparando un entorno de pruebas).
+/// [`test()`](Application::test) si se está preparando un entorno de pruebas).
 pub struct Application;
 
 impl Default for Application {

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)
+    /// El método [`prepare_component()`](crate::core::component::Component::prepare_component)
-    /// delega el renderizado en la función proporcionada, que recibe una referencia mutable
+    /// delega el renderizado en la función proporcionada, que recibe una referencia mutable al
-    /// al contexto de renderizado ([`Context`]).
+    /// contexto de renderizado ([`Context`]).
     pub fn with<F>(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
+    /// [`prepare_component()`](crate::core::component::Component::prepare_component) invoque esta
-    /// esta instancia. La nueva función también recibe una referencia al contexto ([`Context`]).
+    /// instancia. La nueva función también recibe una referencia al contexto ([`Context`]).
     pub fn alter_html<F>(&mut self, f: F) -> &mut Self
     where
         F: Fn(&mut Context) -> Markup + Send + Sync + 'static,

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
+/// Facilita la implementación del método [`actions()`](crate::core::extension::Extension::actions).
-/// [`actions()`](crate::core::extension::ExtensionTrait::actions).
 ///
 /// Evita escribir repetidamente `Box::new(...)` para cada acción de la lista, manteniendo el código
 /// más limpio.

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
+/// implementar explícitamente el método [`new()`](Self::new) y pueden sobrescribir los otros
-/// para personalizar su comportamiento.
+/// métodos para personalizar su comportamiento.
-pub trait ComponentTrait: AnyInfo + ComponentRender + Send + Sync {
+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
+/// 2. Ejecuta [`setup_before_prepare()`](Component::setup_before_prepare) para que el componente
-///    componente pueda ajustar su estructura interna o modificar el contexto.
+///    pueda ajustar su estructura interna o modificar el contexto.
 /// 3. Despacha [`action::theme::BeforeRender<C>`](crate::base::action::theme::BeforeRender) para
 ///    que el tema pueda hacer ajustes en el componente o el contexto.
 /// 4. Despacha [`action::component::BeforeRender<C>`](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<C>`](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
+///    - Si no es así, ejecuta [`prepare_component()`](Component::prepare_component) para preparar
-///      preparar el renderizado predefinido del componente.
+///      el renderizado predefinido del componente.
 /// 6. Despacha [`action::theme::AfterRender<C>`](crate::base::action::theme::AfterRender) para
 ///    que el tema pueda hacer sus últimos ajustes.
 /// 7. Despacha [`action::component::AfterRender<C>`](crate::base::action::component::AfterRender)

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())
     }

src/core/theme/all.rs

@@ -19,7 +19,7 @@ pub static DEFAULT_THEME: LazyLock<ThemeRef> =
 
 // 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<ThemeRef> {
     let short_name = short_name.to_lowercase();
     match THEMES

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á
+    /// [`Context::with_langid()`](crate::html::Context::with_langid); si no se ha definido, se
-    /// el indicado en la cabecera `Accept-Language` del navegador; y, si ninguno aplica, 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

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
+/// > incluirse en el proyecto utilizando [`include_files!`](crate::include_files) y servirse con
-/// > [`include_files_service`](crate::include_files_service).
+/// > [`include_files_service!`](crate::include_files_service).
 ///
 /// # Ejemplo
 ///

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
+/// > Pueden incluirse en el proyecto utilizando [`include_files!`](crate::include_files) y servirse
-/// > con [`include_files_service`](crate::include_files_service).
+/// > con [`include_files_service!`](crate::include_files_service).
 ///
 /// # Ejemplo
 ///

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
+/// > incluirse en el proyecto utilizando [`include_files!`](crate::include_files) y servirse con
-/// > [`include_files_service`](crate::include_files_service).
+/// > [`include_files_service!`](crate::include_files_service).
 ///
 /// # Ejemplo
 ///

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::using()`](crate::locale::L10n::using) o
-/// [`L10n::to_markup`](crate::locale::L10n::to_markup).
+/// [`L10n::to_markup()`](crate::locale::L10n::to_markup).
 impl LangId for Context {
     fn langid(&self) -> &'static LanguageIdentifier {
         self.langid

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
+/// Resulta útil para usar un valor de [`LangMatch`] como fuente de traducción en [`L10n::using()`]
-/// [`L10n::to_markup`].
+/// o [`L10n::to_markup()`].
 impl LangId for LangMatch {
     fn langid(&self) -> &'static LanguageIdentifier {
         match self {

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

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