From e33cb6df85f132930c7dd2cc6598a73defebb162 Mon Sep 17 00:00:00 2001 From: Cameron Garnham Date: Tue, 28 Mar 2023 12:08:07 +0200 Subject: [PATCH] doc: fix basic doc linting errors --- src/tracker/auth.rs | 16 +++++++---- src/tracker/databases/driver.rs | 14 +++++++--- src/tracker/mod.rs | 37 +++++++++++++++++++++----- src/tracker/peer.rs | 20 ++++++++++++-- src/tracker/services/statistics/mod.rs | 4 +-- 5 files changed, 71 insertions(+), 20 deletions(-) diff --git a/src/tracker/auth.rs b/src/tracker/auth.rs index 9068a94f..9fe111e5 100644 --- a/src/tracker/auth.rs +++ b/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); /// diff --git a/src/tracker/databases/driver.rs b/src/tracker/databases/driver.rs index ef9a4eb0..7115bae8 100644 --- a/src/tracker/databases/driver.rs +++ b/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) diff --git a/src/tracker/mod.rs b/src/tracker/mod.rs index ce69b612..faabbe09 100644 --- a/src/tracker/mod.rs +++ b/src/tracker/mod.rs @@ -55,11 +55,19 @@ //! 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::().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), @@ -67,10 +75,11 @@ //! 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, //! 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, //! } @@ -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 //! ``` //! diff --git a/src/tracker/peer.rs b/src/tracker/peer.rs index 3626db93..a5434628 100644 --- a/src/tracker/peer.rs +++ b/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)] diff --git a/src/tracker/services/statistics/mod.rs b/src/tracker/services/statistics/mod.rs index 14376142..ac3ba510 100644 --- a/src/tracker/services/statistics/mod.rs +++ b/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; //! ``` //!