From dc2ff3259e963eee5ad373a5cbf9013e47562135 Mon Sep 17 00:00:00 2001
From: Manuel Cillero <manuel@cillero.es>
Date: Tue, 16 May 2023 21:10:10 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=A9=B9=20Corrige=20estructura=20de=20docu?=
 =?UTF-8?q?mentaci=C3=B3n=20en=20doc.rs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pagetop/Cargo.toml      |  3 +++
 pagetop/src/app.rs      |  2 ++
 pagetop/src/config.rs   |  8 ++++----
 pagetop/src/core.rs     |  8 +++++---
 pagetop/src/db.rs       |  2 ++
 pagetop/src/html.rs     |  2 ++
 pagetop/src/lib.rs      | 12 ++++++------
 pagetop/src/locale.rs   |  2 +-
 pagetop/src/prelude.rs  |  3 +++
 pagetop/src/response.rs |  2 ++
 pagetop/src/server.rs   |  2 ++
 pagetop/src/util.rs     |  2 ++
 12 files changed, 34 insertions(+), 14 deletions(-)

diff --git a/pagetop/Cargo.toml b/pagetop/Cargo.toml
index f98ea975..3e884bd5 100644
--- a/pagetop/Cargo.toml
+++ b/pagetop/Cargo.toml
@@ -80,3 +80,6 @@ tokio = { version = "1.28.1", features = ["macros", "rt-multi-thread"] }
 
 [build-dependencies]
 pagetop-build = { version = "0.0", path = "../pagetop-build" }
+
+[package.metadata.docs.rs]
+all-features = true
diff --git a/pagetop/src/app.rs b/pagetop/src/app.rs
index 5c6a76a3..b1971350 100644
--- a/pagetop/src/app.rs
+++ b/pagetop/src/app.rs
@@ -1,3 +1,5 @@
+//! Instancia y ejecuta una aplicación creada con **PageTop**.
+
 mod figfont;
 
 use crate::core::{module, module::ModuleStaticRef};
diff --git a/pagetop/src/config.rs b/pagetop/src/config.rs
index 860404eb..f3f525bc 100644
--- a/pagetop/src/config.rs
+++ b/pagetop/src/config.rs
@@ -1,4 +1,4 @@
-//! Gestión de la configuración.
+//! Lectura y uso de ajustes de configuración.
 //!
 //! Carga la configuración de la aplicación en forma de pares `clave = valor` recogidos en archivos
 //! [TOML](https://toml.io).
@@ -158,13 +158,13 @@ pub static CONFIG: LazyStatic<ConfigData> = LazyStatic::new(|| {
 });
 
 #[macro_export]
-/// Asigna los ajustes de configuración de tu módulo usando tipos seguros y valores predefinidos.
+/// Define un conjunto de ajustes de configuración usando tipos seguros y valores predefinidos.
 ///
 /// Detiene la aplicación con un panic! si no pueden asignarse los ajustes de configuración.
 ///
 /// Ver [`Cómo añadir ajustes de configuración`](config/index.html#cómo-añadir-ajustes-de-configuración).
 macro_rules! define_config {
-    ( $SETTINGS:ident: $Settings:ty $(, $key:literal => $value:literal)*$(,)* ) => {
+    ( $SETTINGS:ident as $Settings:ty $(, $key:literal => $value:literal)*$(,)* ) => {
         $crate::doc_comment! {
             concat!(
                 "Declara y asigna los valores predefinidos para los ajustes de configuración ",
@@ -274,7 +274,7 @@ pub struct Server {
     pub bind_port: u16,
 }
 
-define_config!(SETTINGS: Settings,
+define_config!(SETTINGS as Settings,
     // [app]
     "app.name"               => "PageTop Application",
     "app.description"        => "Developed with the amazing PageTop framework.",
diff --git a/pagetop/src/core.rs b/pagetop/src/core.rs
index 2ca529f6..2f5c0fa2 100644
--- a/pagetop/src/core.rs
+++ b/pagetop/src/core.rs
@@ -1,11 +1,13 @@
+//! Tipos y funciones esenciales para crear módulos, temas, componentes y acciones.
+
+// API to add new features with modules and themes.
+pub mod module;
+
 // API to build new components.
 pub mod component;
 
 // API to define functions that alter the behavior of PageTop core.
 pub mod hook;
 
-// API to add new features with modules and themes.
-pub mod module;
-
 // Basic theme.
 mod basic;
diff --git a/pagetop/src/db.rs b/pagetop/src/db.rs
index fee92181..035c3fc6 100644
--- a/pagetop/src/db.rs
+++ b/pagetop/src/db.rs
@@ -1,3 +1,5 @@
+//! Acceso unificado y normalizado a base de datos.
+
 use crate::{config, run_now, trace, LazyStatic, ResultExt};
 
 pub use url::Url as DbUri;
diff --git a/pagetop/src/html.rs b/pagetop/src/html.rs
index 6792820c..355cd3ca 100644
--- a/pagetop/src/html.rs
+++ b/pagetop/src/html.rs
@@ -1,3 +1,5 @@
+//! HTML en código.
+
 pub use maud::{html, Markup, PreEscaped, DOCTYPE};
 
 mod assets;
diff --git a/pagetop/src/lib.rs b/pagetop/src/lib.rs
index 9f8d4d0c..ff551e9e 100644
--- a/pagetop/src/lib.rs
+++ b/pagetop/src/lib.rs
@@ -1,6 +1,6 @@
 //! <div align="center">
 //!
-//!   <img src="https://raw.githubusercontent.com/manuelcillero/pagetop/main/pagetop/static/pagetop-banner.png" />
+//!   <img src="https://raw.githubusercontent.com/manuelcillero/pagetop/main/banner/pagetop.png" />
 //!
 //!   <h1>PageTop</h1>
 //!
@@ -12,9 +12,9 @@
 //! **PageTop** es un entorno de desarrollo basado en Rust que reúne algunos de los crates más
 //! estables y populares para crear soluciones web modulares, extensibles y configurables.
 //!
-//! PageTop añade una capa de abstracción para definir una interfaz única que ofrezca de partida:
+//! PageTop define un interfaz único que ofrece:
 //!
-//!  * Gestión de la configuración ([`config`]).
+//!  * Lectura y uso de ajustes de configuración ([`config`]).
 //!
 //!  * Registro de trazas y eventos de la aplicación ([`trace`]).
 //!
@@ -22,9 +22,9 @@
 //!
 //!  * HTML en código ([`html`]).
 //!
-//!  * Acceso a base de datos ([`db`]).
+//!  * Acceso unificado y normalizado a base de datos ([`db`]).
 //!
-//!  * APIs esenciales para crear componentes, acciones, módulos y temas ([`core`]).
+//!  * Tipos y funciones esenciales para crear módulos, temas, componentes y acciones ([`core`]).
 //!
 //!  * Tipos de respuestas a peticiones web ([`response`])
 //!
@@ -76,7 +76,7 @@ pub mod html;
 #[cfg(feature = "database")]
 pub mod db;
 
-// APIs esenciales para crear componentes, acciones, módulos y temas.
+// APIs esenciales para crear módulos, temas, componentes y acciones.
 pub mod core;
 
 // API del servidor web.
diff --git a/pagetop/src/locale.rs b/pagetop/src/locale.rs
index f9171bf1..f067bf4c 100644
--- a/pagetop/src/locale.rs
+++ b/pagetop/src/locale.rs
@@ -122,7 +122,7 @@ pub static LANGID: LazyStatic<LanguageIdentifier> =
     });
 
 #[macro_export]
-/// Permite integrar fácilmente localización en temas, módulos y componentes.
+/// Define un conjunto de elementos de localización y funciones locales de traducción.
 macro_rules! define_locale {
     ( $dir_locales:literal $(, $core_locales:literal)? ) => {
         use $crate::locale::*;
diff --git a/pagetop/src/prelude.rs b/pagetop/src/prelude.rs
index 30d2c5c3..f93d7bdb 100644
--- a/pagetop/src/prelude.rs
+++ b/pagetop/src/prelude.rs
@@ -1,3 +1,6 @@
+//! Re-exporta los tipos y funciones más habituales para la creación de soluciones web con
+//! **PageTop**.
+
 // Re-exports.
 pub use crate::{concat_string, fn_builder, Handle, HashMapResources, LazyStatic, ResultExt};
 
diff --git a/pagetop/src/response.rs b/pagetop/src/response.rs
index 5c165979..569dcf50 100644
--- a/pagetop/src/response.rs
+++ b/pagetop/src/response.rs
@@ -1,3 +1,5 @@
+//! Tipos de respuestas a peticiones web.
+
 pub use actix_web::ResponseError;
 
 pub mod page;
diff --git a/pagetop/src/server.rs b/pagetop/src/server.rs
index 06c63242..17f145a5 100644
--- a/pagetop/src/server.rs
+++ b/pagetop/src/server.rs
@@ -1,3 +1,5 @@
+//! Tipos y funciones para operar con el servidor web ([actix-web](https://docs.rs/actix-web)).
+
 pub use actix_web::{
     http, web, App, HttpMessage, HttpRequest, HttpResponse, HttpServer, Responder,
 };
diff --git a/pagetop/src/util.rs b/pagetop/src/util.rs
index 727ef557..986f43d4 100644
--- a/pagetop/src/util.rs
+++ b/pagetop/src/util.rs
@@ -1,3 +1,5 @@
+//! Funciones útiles.
+
 use crate::Handle;
 
 // https://stackoverflow.com/a/71464396