Lint Documentation

.github/workflows/test_build_release.yml

@@ -34,6 +34,8 @@ jobs:
         run: cargo check --all-targets
       - name: Clippy Rust Code
         run: cargo clippy --all-targets -- -D clippy::pedantic
+      - name: Test Documentation
+        run: cargo test --doc
       - uses: taiki-e/install-action@cargo-llvm-cov
       - uses: taiki-e/install-action@nextest
       - name: Run Tests

src/tracker/auth.rs

@@ -12,6 +12,9 @@
 //! Keys are stored in this struct:
 //!
 //! ```rust,no_run
+//! use torrust_tracker::tracker::auth::Key;
+//! use torrust_tracker::shared::clock::DurationSinceUnixEpoch;
+//!
 //! pub struct ExpiringKey {
 //!     /// Random 32-char string. For example: `YZSl4lMZupRuOpSRC3krIKR5BPB14nrJ`
 //!     pub key: Key,
@@ -23,16 +26,16 @@
 //! You can generate a new key valid for `9999` seconds and `0` nanoseconds from the current time with the following:
 //!
 //! ```rust,no_run
-//! let expiring_key = auth::generate(Duration::new(9999, 0));
+//! use torrust_tracker::tracker::auth;
+//! use std::time::Duration;
 //!
-//! assert!(auth::verify(&expiring_key).is_ok());
-//! ```
+//! let expiring_key = auth::generate(Duration::new(9999, 0));
 //!
-//! And you can later verify it with:
+//! // And you can later verify it with:
 //!
-//! ```rust,no_run
 //! assert!(auth::verify(&expiring_key).is_ok());
 //! ```
+
 use std::panic::Location;
 use std::str::FromStr;
 use std::sync::Arc;
@@ -135,6 +138,9 @@ pub struct Key(String);
 /// Error returned when a key cannot be parsed from a string.
 ///
 /// ```rust,no_run
+/// use torrust_tracker::tracker::auth::Key;
+/// use std::str::FromStr;
+///
 /// let key_string = "YZSl4lMZupRuOpSRC3krIKR5BPB14nrJ";
 /// let key = Key::from_str(key_string);
 ///

src/tracker/databases/driver.rs

@@ -14,17 +14,23 @@ use super::{Builder, Database};
 /// Example for `SQLite3`:
 ///
 /// ```rust,no_run
-/// let db_driver = "Sqlite3".to_string();
+/// use torrust_tracker::tracker::databases;
+/// use torrust_tracker_primitives::DatabaseDriver;
+///
+/// let db_driver = DatabaseDriver::Sqlite3;
 /// let db_path = "./storage/database/data.db".to_string();
-/// let database = databases::driver::build(&db_driver, &db_path)?;
+/// let database = databases::driver::build(&db_driver, &db_path);
 /// ```
 ///
 /// Example for `MySQL`:
 ///
 /// ```rust,no_run
-/// let db_driver = "MySQL".to_string();
+/// use torrust_tracker::tracker::databases;
+/// use torrust_tracker_primitives::DatabaseDriver;
+///
+/// let db_driver = DatabaseDriver::MySQL;
 /// let db_path = "mysql://db_user:db_user_secret_password@mysql:3306/torrust_tracker".to_string();
-/// let database = databases::driver::build(&db_driver, &db_path)?;
+/// let database = databases::driver::build(&db_driver, &db_path);
 /// ```
 ///
 /// Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration)

src/tracker/mod.rs

@@ -55,22 +55,31 @@
 //! Once you have instantiated the `Tracker` you can `announce` a new [`peer`](crate::tracker::peer::Peer) with:
 //!
 //! ```rust,no_run
-//! let info_hash = InfoHash {
-//!     "3b245504cf5f11bbdbe1201cea6a6bf45aee1bc0".parse::<InfoHash>().unwrap()
-//! };
+//! use torrust_tracker::tracker::peer;
+//! use torrust_tracker::shared::bit_torrent::info_hash::InfoHash;
+//! use torrust_tracker::shared::clock::DurationSinceUnixEpoch;
+//! use aquatic_udp_protocol::{AnnounceEvent, NumberOfBytes};
+//! use std::net::SocketAddr;
+//! use std::net::IpAddr;
+//! use std::net::Ipv4Addr;
+//! use std::str::FromStr;
+//!
+//!
+//! let info_hash = InfoHash::from_str("3b245504cf5f11bbdbe1201cea6a6bf45aee1bc0").unwrap();
 //!
-//! let peer = Peer {
+//! let peer = peer::Peer {
 //!     peer_id: peer::Id(*b"-qB00000000000000001"),
 //!     peer_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::new(126, 0, 0, 1)), 8081),
 //!     updated: DurationSinceUnixEpoch::new(1_669_397_478_934, 0),
 //!     uploaded: NumberOfBytes(0),
 //!     downloaded: NumberOfBytes(0),
 //!     left: NumberOfBytes(0),
 //!     event: AnnounceEvent::Completed,
-//! }
+//! };
 //!
 //! let peer_ip = IpAddr::V4(Ipv4Addr::from_str("126.0.0.1").unwrap());
-//!
+//! ```
+//! ```rust,ignore
 //! let announce_data = tracker.announce(&info_hash, &mut peer, &peer_ip).await;
 //! ```
 //!
@@ -87,6 +96,8 @@
 //! The returned struct is:
 //!
 //! ```rust,no_run
+//! use torrust_tracker::tracker::peer::Peer;
+//!
 //! pub struct AnnounceData {
 //!     pub peers: Vec<Peer>,
 //!     pub swarm_stats: SwarmStats,
@@ -124,6 +135,9 @@
 //! The returned struct is:
 //!
 //! ```rust,no_run
+//! use torrust_tracker::shared::bit_torrent::info_hash::InfoHash;
+//! use std::collections::HashMap;
+//!
 //! pub struct ScrapeData {
 //!     pub files: HashMap<InfoHash, SwarmMetadata>,
 //! }
@@ -150,6 +164,9 @@
 //! There are two data structures for infohashes: byte arrays and hex strings:
 //!
 //! ```rust,no_run
+//! use torrust_tracker::shared::bit_torrent::info_hash::InfoHash;
+//! use std::str::FromStr;
+//!
 //! let info_hash: InfoHash = [255u8; 20].into();
 //!
 //! assert_eq!(
@@ -233,6 +250,12 @@
 //! A `Peer` is the struct used by the `Tracker` to keep peers data:
 //!
 //! ```rust,no_run
+//! use torrust_tracker::tracker::peer::Id;
+//! use std::net::SocketAddr;
+//! use torrust_tracker::shared::clock::DurationSinceUnixEpoch;
+//! use aquatic_udp_protocol::NumberOfBytes;
+//! use aquatic_udp_protocol::AnnounceEvent;
+//!
 //! pub struct Peer {
 //!     pub peer_id: Id,                     // The peer ID
 //!     pub peer_addr: SocketAddr,           // Peer socket address
@@ -389,7 +412,7 @@
 //!
 //! For example, the HTTP tracker would send an event like the following when it handles an `announce` request received from a peer using IP version 4.
 //!
-//! ```rust,no_run
+//! ```rust,ignore
 //! tracker.send_stats_event(statistics::Event::Tcp4Announce).await
 //! ```
 //!

src/tracker/peer.rs

@@ -3,6 +3,13 @@
 //! A sample peer:
 //!
 //! ```rust,no_run
+//! use torrust_tracker::tracker::peer;
+//! use std::net::SocketAddr;
+//! use std::net::IpAddr;
+//! use std::net::Ipv4Addr;
+//! use torrust_tracker::shared::clock::DurationSinceUnixEpoch;
+//! use aquatic_udp_protocol::{AnnounceEvent, NumberOfBytes};
+//!
 //! peer::Peer {
 //!     peer_id: peer::Id(*b"-qB00000000000000000"),
 //!     peer_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::new(126, 0, 0, 1)), 8080),
@@ -11,7 +18,7 @@
 //!     downloaded: NumberOfBytes(0),
 //!     left: NumberOfBytes(0),
 //!     event: AnnounceEvent::Started,
-//! }
+//! };
 //! ```
 use std::net::{IpAddr, SocketAddr};
 use std::panic::Location;
@@ -39,6 +46,13 @@ pub enum IPVersion {
 /// A sample peer:
 ///
 /// ```rust,no_run
+/// use torrust_tracker::tracker::peer;
+/// use std::net::SocketAddr;
+/// use std::net::IpAddr;
+/// use std::net::Ipv4Addr;
+/// use torrust_tracker::shared::clock::DurationSinceUnixEpoch;
+/// use aquatic_udp_protocol::{AnnounceEvent, NumberOfBytes};
+///
 /// peer::Peer {
 ///     peer_id: peer::Id(*b"-qB00000000000000000"),
 ///     peer_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::new(126, 0, 0, 1)), 8080),
@@ -47,7 +61,7 @@ pub enum IPVersion {
 ///     downloaded: NumberOfBytes(0),
 ///     left: NumberOfBytes(0),
 ///     event: AnnounceEvent::Started,
-/// }
+/// };
 /// ```
 #[derive(PartialEq, Eq, Debug, Clone, Serialize, Copy)]
 pub struct Peer {
@@ -104,6 +118,8 @@ impl Peer {
 /// A sample peer ID:
 ///
 /// ```rust,no_run
+/// use torrust_tracker::tracker::peer;
+///
 /// let peer_id = peer::Id(*b"-qB00000000000000000");
 /// ```
 #[derive(PartialEq, Eq, Hash, Clone, Debug, PartialOrd, Ord, Copy)]

src/tracker/services/statistics/mod.rs

@@ -12,7 +12,7 @@
 //! - An statistics [`EventSender`](crate::tracker::statistics::EventSender)
 //! - An statistics [`Repo`](crate::tracker::statistics::Repo)
 //!
-//! ```rust,no_run
+//! ```rust,ignore
 //! let (stats_event_sender, stats_repository) = factory(tracker_usage_statistics);
 //! ```
 //!
@@ -23,7 +23,7 @@
 //!
 //! For example, if you send the event [`Event::Udp4Connect`](crate::tracker::statistics::Event::Udp4Connect):
 //!
-//! ```rust,no_run
+//! ```rust,ignore
 //! let result = event_sender.send_event(Event::Udp4Connect).await;
 //! ```
 //!