Improve documentation
This commit is contained in:
parent
2c97dd7a70
commit
a312c3097f
41
src/lib.rs
41
src/lib.rs
|
@ -1,4 +1,18 @@
|
|||
//! A simple IRC crate written in rust
|
||||
//! ```rust
|
||||
//! fn main() -> Result<(), std::io::Error> {
|
||||
//! let config = Config::from_toml("config.toml")?;
|
||||
//! let mut client = Client::new(config)?;
|
||||
//! client.identify()?;
|
||||
//!
|
||||
//! loop {
|
||||
//! if let Ok(ref command) = client.read() {
|
||||
//! if let Command::OTHER(line) = command {
|
||||
//! print!("{}", line);
|
||||
//! }
|
||||
//! }
|
||||
//! }
|
||||
//! }
|
||||
|
||||
#![warn(missing_docs)]
|
||||
use std::borrow::Cow;
|
||||
|
@ -40,7 +54,7 @@ pub enum Command {
|
|||
CAP(CapMode),
|
||||
/// Joins a channel
|
||||
/// ```rust
|
||||
/// client.write_command(Command::PRIVMSG("#main".to_string()))?;
|
||||
/// client.write_command(Command::JOIN("#main".to_string()))?;
|
||||
/// ```
|
||||
JOIN(
|
||||
/// Channel
|
||||
|
@ -50,6 +64,7 @@ pub enum Command {
|
|||
/// ```rust
|
||||
/// client.write_command(Command::MODE("#main".to_string(), Some("+B")))?;
|
||||
/// ```
|
||||
/// If the MODE is not given (e.g. None), then the client will send "MODE target"
|
||||
MODE(
|
||||
/// Channel
|
||||
String,
|
||||
|
@ -60,9 +75,9 @@ pub enum Command {
|
|||
NICK(String),
|
||||
/// Everything that is not a command
|
||||
OTHER(String),
|
||||
/// Ping another user
|
||||
/// Ping another user or the server
|
||||
PING(
|
||||
/// User
|
||||
/// target
|
||||
String,
|
||||
),
|
||||
#[doc(hidden)]
|
||||
|
@ -99,15 +114,19 @@ impl Client {
|
|||
/// ```rust
|
||||
/// let mut client = Client::new(config)?;
|
||||
/// ```
|
||||
///
|
||||
/// Errors if the client could not connect to the given host.
|
||||
pub fn new(config: Config) -> Result<Self, Error> {
|
||||
let stream = TcpStream::connect(format!("{}:{}", config.host, config.port))?;
|
||||
Ok(Self { stream, config })
|
||||
}
|
||||
|
||||
/// Identify user and join the IRC
|
||||
/// Identify user and join the specified channels
|
||||
/// ```rust
|
||||
/// client.identify()?;
|
||||
/// ```
|
||||
///
|
||||
/// Errors if the client could not write to the stream.
|
||||
pub fn identify(&mut self) -> Result<(), Error> {
|
||||
self.write_command(Command::CAP(CapMode::END))?;
|
||||
self.write_command(Command::USER(
|
||||
|
@ -157,7 +176,7 @@ impl Client {
|
|||
Some(String::from_utf8_lossy(&buffer).into())
|
||||
}
|
||||
|
||||
/// Read data comming from the IRC
|
||||
/// Read data coming from the IRC as a [`Command`]
|
||||
/// ```rust
|
||||
/// if let Ok(ref command) = client.read() {
|
||||
/// if let Command::OTHER(line) = command {
|
||||
|
@ -165,6 +184,8 @@ impl Client {
|
|||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Errors if there are no new messages. This should not be taken as an actual Error, because nothing went wrong.
|
||||
pub fn read(&mut self) -> Result<Command, ()> {
|
||||
if let Some(string) = self.read_string() {
|
||||
return Ok(Command::from_str(&string));
|
||||
|
@ -184,10 +205,12 @@ impl Client {
|
|||
Ok(())
|
||||
}
|
||||
|
||||
/// Send a command to the IRC
|
||||
/// Send a [`Command`] to the IRC
|
||||
/// ```rust
|
||||
/// client.write_command(Command::PRIVMSG("#main".to_string(), "Hello".to_string()))?;
|
||||
/// ```
|
||||
///
|
||||
/// Errors if the stream could not write.
|
||||
pub fn write_command(&mut self, command: Command) -> Result<(), Error> {
|
||||
use Command::*;
|
||||
let computed = match command {
|
||||
|
@ -251,8 +274,8 @@ impl Config {
|
|||
/// <br>
|
||||
/// channels: Channels to join on the IRC<br>
|
||||
/// host: IP or domain of the IRC server<br>
|
||||
/// mode: Mode to join the IRC with<br>
|
||||
/// nickname: Nickname to join the IRC with<br>
|
||||
/// mode: Mode to join the IRC with (optional)<br>
|
||||
/// nickname: Nickname to join the IRC with (optional, defaults to the given username)<br>
|
||||
/// port: Port of the IRC server<br>
|
||||
/// username: Username to join the IRC with<br>
|
||||
/// ```rust
|
||||
|
@ -296,6 +319,8 @@ impl Config {
|
|||
/// port = 6667
|
||||
/// username = "IRSC"
|
||||
/// ```
|
||||
///
|
||||
/// Returns an Error if the file cannot be opened or if the TOML is invalid
|
||||
pub fn from_toml<P: AsRef<Path>>(path: P) -> Result<Self, Error> {
|
||||
let mut file = File::open(&path)?;
|
||||
let mut data = String::new();
|
||||
|
|
Loading…
Reference in a new issue