♻️ Refactoriza la gestión de regiones y plantillas

src/core/extension/definition.rs

@@ -4,24 +4,23 @@ use crate::core::AnyInfo;
 use crate::locale::L10n;
 use crate::{actions_boxed, service};
 
-/// Representa una referencia a una extensión.
-///
-/// Las extensiones se definen como instancias estáticas globales para poder acceder a ellas desde
-/// cualquier hilo de la ejecución sin necesidad de sincronización adicional.
-pub type ExtensionRef = &'static dyn Extension;
-
 /// Interfaz común que debe implementar cualquier extensión de PageTop.
 ///
-/// Este *trait* es fácil de implementar, basta con declarar una estructura de tamaño cero para la
-/// extensión y sobreescribir los métodos que sea necesario.
+/// Este *trait* es fácil de implementar, basta con declarar una estructura sin campos para la
+/// extensión y sobrescribir los métodos que sean necesarios. Por ejemplo:
 ///
 /// ```rust
 /// # use pagetop::prelude::*;
 /// pub struct Blog;
 ///
 /// impl Extension for Blog {
-///     fn name(&self) -> L10n { L10n::n("Blog") }
-///     fn description(&self) -> L10n { L10n::n("Blog system") }
+///     fn name(&self) -> L10n {
+///         L10n::n("Blog")
+///     }
+///
+///     fn description(&self) -> L10n {
+///         L10n::n("Blog system")
+///     }
 /// }
 /// ```
 pub trait Extension: AnyInfo + Send + Sync {
@@ -34,14 +33,19 @@ pub trait Extension: AnyInfo + Send + Sync {
     }
 
     /// Descripción corta localizada de la extensión para paneles, listados, etc.
+    ///
+    /// Por defecto devuelve un valor vacío (`L10n::default()`).
     fn description(&self) -> L10n {
         L10n::default()
     }
 
-    /// Devuelve una referencia a esta misma extensión cuando se trata de un tema.
+    /// Devuelve una referencia a esta misma extensión cuando actúa como un tema.
     ///
-    /// Para ello, debe implementar [`Extension`] y también [`Theme`](crate::core::theme::Theme). Si
-    /// la extensión no es un tema, este método devuelve `None` por defecto.
+    /// Para ello, la implementación concreta debe ser una extensión que también implemente
+    /// [`Theme`](crate::core::theme::Theme). Por defecto, asume que la extensión no es un tema y
+    /// devuelve `None`.
+    ///
+    /// # Ejemplo
     ///
     /// ```rust
     /// # use pagetop::prelude::*;
@@ -61,17 +65,17 @@ pub trait Extension: AnyInfo + Send + Sync {
 
     /// Otras extensiones que deben habilitarse **antes** de esta.
     ///
-    /// PageTop las resolverá automáticamente respetando el orden durante el arranque de la
-    /// aplicación.
+    /// PageTop resolverá automáticamente estas dependencias respetando el orden durante el arranque
+    /// de la aplicación.
     fn dependencies(&self) -> Vec<ExtensionRef> {
         vec![]
     }
 
-    /// Devuelve la lista de acciones que la extensión va a registrar.
+    /// Devuelve la lista de acciones que la extensión registra.
     ///
     /// Estas [acciones](crate::core::action) se despachan por orden de registro o por
-    /// [peso](crate::Weight), permitiendo personalizar el comportamiento de la aplicación en puntos
-    /// específicos.
+    /// [peso](crate::Weight) (ver [`actions_boxed!`](crate::actions_boxed)), permitiendo
+    /// personalizar el comportamiento de la aplicación en puntos específicos.
     fn actions(&self) -> Vec<ActionBox> {
         actions_boxed![]
     }
@@ -85,6 +89,8 @@ pub trait Extension: AnyInfo + Send + Sync {
     /// Configura los servicios web de la extensión, como rutas, *middleware*, acceso a ficheros
     /// estáticos, etc., usando [`ServiceConfig`](crate::service::web::ServiceConfig).
     ///
+    /// # Ejemplo
+    ///
     /// ```rust,ignore
     /// # use pagetop::prelude::*;
     /// pub struct ExtensionSample;
@@ -98,11 +104,15 @@ pub trait Extension: AnyInfo + Send + Sync {
     #[allow(unused_variables)]
     fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {}
 
-    /// Permite crear extensiones para deshabilitar y desinstalar recursos de otras de versiones
-    /// anteriores de la aplicación.
+    /// Permite declarar extensiones destinadas a deshabilitar o desinstalar recursos de otras
+    /// extensiones asociadas a versiones anteriores de la aplicación.
     ///
-    /// Actualmente no se usa, pero se deja como *placeholder* para futuras implementaciones.
+    /// Actualmente PageTop no utiliza este método, pero se reserva como *placeholder* para futuras
+    /// implementaciones.
     fn drop_extensions(&self) -> Vec<ExtensionRef> {
         vec![]
     }
 }
+
+/// Representa una referencia a una extensión.
+pub type ExtensionRef = &'static dyn Extension;