Improve documentation

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>
+    /// mode: Mode to join the IRC with (optional)<br>
-    /// nickname: Nickname to join the IRC with<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();