From 8ed4820e0b553b1c6f7e6738e654335fbe0d730d Mon Sep 17 00:00:00 2001 From: famfo Date: Wed, 5 Jan 2022 11:53:57 +0100 Subject: [PATCH] Fixed documentation --- Cargo.toml | 2 +- README.md | 17 ++++- examples/basic-config/Cargo.lock | 2 +- examples/basic-config/src/main.rs | 2 +- examples/config-from-toml/Cargo.lock | 2 +- examples/config-from-toml/src/main.rs | 2 +- examples/debugging/src/main.rs | 4 +- src/commands.rs | 75 ++++--------------- src/lib.rs | 104 +++++++------------------- 9 files changed, 63 insertions(+), 147 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index cd9f625..73bde42 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,7 +8,7 @@ license = "Unlicense" name = "async-circe" readme = "README.md" repository = "https://git.karx.xyz/circe/async-circe.git" -version = "0.2.2" +version = "0.2.3" [dependencies.toml] version = "0.5" diff --git a/README.md b/README.md index 597e5a7..c1c2df6 100644 --- a/README.md +++ b/README.md @@ -11,21 +11,30 @@ To start using Circe, just add the crate to your `Cargo.toml`, and then follow the example below. ```rust -use circe::{Client, Config, Command}; +use async_circe::{commands::Command, Client, Config}; -fn main() -> Result<(), std::io::Error> { - let config = Default::default(); +#[tokio::main(flavor = "current_thread")] +async fn main() -> Result<(), tokio::io::Error> { + let config = Config::new( + &["#chaos", "#async-circe"], + "karx.xyz", + Some("+B"), + Some("async-circe"), + 6697, + "circe", + ); let mut client = Client::new(config).await.unwrap(); client.identify().await.unwrap(); loop { - if let Ok(ref command) = client.read().await { + if let Some(command) = client.read().await? { if let Command::PRIVMSG(nick, channel, message) = command { println!("{} in {}: {}", nick, channel, message); } } } } + ``` Happy hacking! diff --git a/examples/basic-config/Cargo.lock b/examples/basic-config/Cargo.lock index 38eed0b..e09890a 100644 --- a/examples/basic-config/Cargo.lock +++ b/examples/basic-config/Cargo.lock @@ -4,7 +4,7 @@ version = 3 [[package]] name = "async-circe" -version = "0.2.0" +version = "0.2.2" dependencies = [ "native-tls", "tokio", diff --git a/examples/basic-config/src/main.rs b/examples/basic-config/src/main.rs index 006fc2d..dd621f1 100644 --- a/examples/basic-config/src/main.rs +++ b/examples/basic-config/src/main.rs @@ -14,7 +14,7 @@ async fn main() -> Result<(), tokio::io::Error> { client.identify().await.unwrap(); loop { - if let Some(ref command) = client.read().await? { + if let Some(command) = client.read().await? { if let Command::PRIVMSG(nick, channel, message) = command { println!("{} in {}: {}", nick, channel, message); } diff --git a/examples/config-from-toml/Cargo.lock b/examples/config-from-toml/Cargo.lock index dd9e239..84b9786 100644 --- a/examples/config-from-toml/Cargo.lock +++ b/examples/config-from-toml/Cargo.lock @@ -4,7 +4,7 @@ version = 3 [[package]] name = "async-circe" -version = "0.2.0" +version = "0.2.2" dependencies = [ "native-tls", "serde", diff --git a/examples/config-from-toml/src/main.rs b/examples/config-from-toml/src/main.rs index 3362808..4488002 100644 --- a/examples/config-from-toml/src/main.rs +++ b/examples/config-from-toml/src/main.rs @@ -7,7 +7,7 @@ async fn main() -> Result<(), std::io::Error> { client.identify().await.unwrap(); loop { - if let Some(ref command) = client.read().await? { + if let Some(command) = client.read().await? { if let Command::PRIVMSG(nick, channel, message) = command { println!("{} in {}: {}", nick, channel, message); } diff --git a/examples/debugging/src/main.rs b/examples/debugging/src/main.rs index 77cd873..45b9cbc 100644 --- a/examples/debugging/src/main.rs +++ b/examples/debugging/src/main.rs @@ -3,7 +3,7 @@ use async_circe::{commands::Command, Client, Config}; #[tokio::main(flavor = "current_thread")] async fn main() -> Result<(), tokio::io::Error> { // This tells tracing to show the debug log when the binary is run with - // CIRCE_LOG="debug" + // CIRCE_LOG="tracing" tracing_subscriber::fmt() .with_env_filter(tracing_subscriber::EnvFilter::from_env("CIRCE_LOG")) .init(); @@ -20,7 +20,7 @@ async fn main() -> Result<(), tokio::io::Error> { client.identify().await.unwrap(); loop { - if let Some(ref command) = client.read().await? { + if let Some(command) = client.read().await? { if let Command::PRIVMSG(nick, channel, message) = command { println!("{} in {}: {}", nick, channel, message); } diff --git a/src/commands.rs b/src/commands.rs index 4c5c82c..43d6121 100644 --- a/src/commands.rs +++ b/src/commands.rs @@ -17,15 +17,12 @@ pub enum Command { // SQUIT // /// Request information about the admin of a given server. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.admin("libera.chat").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -34,15 +31,12 @@ pub enum Command { String, ), /// Set the status of the client. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.away("afk").await?; /// # Ok(()) - /// # } /// ``` AWAY( /// Message @@ -51,15 +45,12 @@ pub enum Command { #[doc(hidden)] CAP(CapMode), /// Invite someone to a channel. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.invite("liblemonirc", "#async_circe").await?; /// # Ok(()) - /// # } /// ``` INVITE( /// User @@ -68,30 +59,24 @@ pub enum Command { String, ), /// Join a channel. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.join("#main").await?; /// # Ok(()) - /// # } /// ``` JOIN( /// Channel String, ), /// List available channels on an IRC, or users in a channel. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.list(None, None).await?; /// # Ok(()) - /// # } /// ``` LIST( /// Channel @@ -100,15 +85,12 @@ pub enum Command { Option, ), /// Set the mode for a user. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.mode("test", Some("+B")).await?; /// # Ok(()) - /// # } /// ``` MODE( /// Channel @@ -117,15 +99,12 @@ pub enum Command { Option, ), /// Get all the people online in channels. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.names("#main,#async_circe", None).await?; /// # Ok(()) - /// # } /// ``` NAMES( /// Channel @@ -134,30 +113,24 @@ pub enum Command { Option, ), /// Change your nickname on a server. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.nick("Not async-circe").await?; /// # Ok(()) - /// # } /// ``` NICK( /// Nickname String, ), /// Authentificate as an operator on a server. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.oper("username", "password").await?; /// # Ok(()) - /// # } /// ``` OPER( /// Username @@ -168,15 +141,12 @@ pub enum Command { /// Everything that is not a command OTHER(String), /// Leave a channel. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.part("#main").await?; /// # Ok(()) - /// # } /// ``` PART( /// Target @@ -185,29 +155,23 @@ pub enum Command { #[doc(hidden)] PASS(String), /// Tests the presence of a connection to a server. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.ping("libera.chat", None).await?; /// # Ok(()) - /// # } /// ``` PING(String), #[doc(hidden)] PONG(String), /// Send a message to a channel. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.privmsg("#main", "Hello").await?; /// # Ok(()) - /// # } /// ``` PRIVMSG( /// Source Nickname @@ -218,15 +182,12 @@ pub enum Command { String, ), /// Leave the IRC server you are connected to. - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.quit(None).await?; /// # Ok(()) - /// # } /// ``` QUIT( /// Leave message @@ -234,27 +195,21 @@ pub enum Command { ), /// Get the topic of a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.topic("#main", None).await?; /// # Ok(()) - /// # } /// ``` /// Set the topic of a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.topic("#main", Some("main channel")).await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. diff --git a/src/lib.rs b/src/lib.rs index 5d6a3e9..f8d2b0c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,5 @@ //! A simple IRC crate written in rust -//! ```no_run +//! ```run_fut //! use async_circe::{commands::Command, Client, Config}; //! //! #[tokio::main(flavor = "current_thread")] @@ -73,13 +73,10 @@ pub struct Config { impl Client { /// Creates a new client with a given [`Config`]. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// let mut client = Client::new(config).await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns error if the client could not connect to the host. @@ -116,14 +113,11 @@ impl Client { /// Identify user and joins the in the [`Config`] specified channels. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// client.identify().await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns error if the client could not write to the stream. @@ -203,9 +197,8 @@ impl Client { /// Read data coming from the IRC as a [`commands::Command`]. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut + /// # use async_circe::*; /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; @@ -218,7 +211,6 @@ impl Client { /// # break; /// } /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -248,15 +240,13 @@ impl Client { /// Request information about the admin of a given server. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut + /// # use async_circe::*; /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.admin("libera.chat").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -267,15 +257,12 @@ impl Client { /// Set the status of the client. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.away("afk").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -296,15 +283,12 @@ impl Client { /// Invite someone to a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.invite("liblemonirc", "#async_circe").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -316,15 +300,12 @@ impl Client { /// Join a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.join("#main").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -335,15 +316,12 @@ impl Client { /// List available channels on an IRC, or users in a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.list(None, None).await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -362,15 +340,12 @@ impl Client { /// Set the mode for a user. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.mode("test", Some("+B")).await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -385,15 +360,12 @@ impl Client { /// Get all the people online in channels. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.names("#main,#async_circe", None).await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -409,15 +381,12 @@ impl Client { /// Change your nickname on a server. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.nick("Not async-circe").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -428,15 +397,12 @@ impl Client { /// Authentificate as an operator on a server. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.oper("username", "password").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -448,15 +414,12 @@ impl Client { /// Leave a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.part("#main").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -473,15 +436,12 @@ impl Client { /// Tests the presence of a connection to a server. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.ping("libera.chat", None).await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -504,15 +464,12 @@ impl Client { /// Send a message to a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.privmsg("#main", "Hello").await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -524,15 +481,13 @@ impl Client { /// Leave the IRC server you are connected to. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut + /// # use async_circe::*; /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.quit(None).await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -553,27 +508,22 @@ impl Client { /// Get the topic of a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut + /// # use async_circe::*; /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.topic("#main", None).await?; /// # Ok(()) - /// # } /// ``` /// Set the topic of a channel. /// # Example - /// ```no_run - /// # #[tokio::main(flavor = "current_thread")] - /// # async fn main() -> Result<(), tokio::io::Error> { + /// ```run_fut /// # let config = Default::default(); /// # let mut client = Client::new(config).await?; /// # client.identify().await?; /// client.topic("#main", Some("main channel")).await?; /// # Ok(()) - /// # } /// ``` /// # Errors /// Returns IO errors from the TcpStream. @@ -605,6 +555,7 @@ impl Config { /// Create a new config for the client /// # Example /// ```rust + /// # use async_circe::Config; /// let config = Config::new( /// &["#main", "#async_circe"], /// "karx.xyz", @@ -659,9 +610,10 @@ impl Config { /// Allows for configuring async-circe at runtime. /// # Example - /// ```no_run + /// ```run_fut + /// # use async_circe::Config; /// let config = Config::runtime_config( - /// vev!["#main".to_string(), "#async_circe".to_string()], + /// vec!["#main".to_string(), "#async_circe".to_string()], /// "karx.xyz".to_string(), /// Some("+B".to_string()), /// Some("async-circe".to_string()), @@ -717,7 +669,7 @@ impl Config { /// port = 6667 /// username = "circe" /// ``` - /// ```no_run + /// ```run_fut /// let config = Config::from_toml("Config.toml")?; /// ``` /// # Errors