more documentation \o/

lumi created 9 years ago

Change summary

src/error.rs  |  3 +++
src/event.rs  | 31 +++++++++++++++++++++++++++++++
src/jid.rs    |  2 ++
src/plugin.rs |  2 ++
4 files changed, 38 insertions(+)

Detailed changes

src/error.rs

@@ -1,3 +1,5 @@
+//! Provides an `Error` for use in this crate.
+
 use std::io;
 
 use std::net::TcpStream;
@@ -10,6 +12,7 @@ use xml::writer::Error as EmitterError;
 
 use minidom::Error as MinidomError;
 
+/// An error which wraps a bunch of errors from different crates and the stdlib.
 #[derive(Debug)]
 pub enum Error {
     XmlError(XmlError),

src/event.rs

@@ -1,25 +1,56 @@
+//! Provides an abstract event type which can be downcasted into a more specific one.
+//!
+//! # Examples
+//!
+//! ```
+//! use xmpp::event::{Event, AbstractEvent};
+//!
+//! #[derive(Debug, PartialEq, Eq)]
+//! struct EventA;
+//!
+//! impl Event for EventA {}
+//!
+//! #[derive(Debug, PartialEq, Eq)]
+//! struct EventB;
+//!
+//! impl Event for EventB {}
+//!
+//! let event_a = AbstractEvent::new(EventA);
+//!
+//! assert_eq!(event_a.is::<EventA>(), true);
+//! assert_eq!(event_a.is::<EventB>(), false);
+//!
+//! assert_eq!(event_a.downcast::<EventA>(), Some(&EventA));
+//! assert_eq!(event_a.downcast::<EventB>(), None);
+//! ```
+
 use std::fmt::Debug;
 
 use std::any::Any;
 
+/// An abstract event.
 pub struct AbstractEvent {
     inner: Box<Any>,
 }
 
 impl AbstractEvent {
+    /// Creates an abstract event from a concrete event.
     pub fn new<E: Event>(event: E) -> AbstractEvent {
         AbstractEvent {
             inner: Box::new(event),
         }
     }
 
+    /// Downcasts this abstract event into a concrete event.
     pub fn downcast<E: Event + 'static>(&self) -> Option<&E> {
         self.inner.downcast_ref::<E>()
     }
 
+    /// Checks whether this abstract event is a specific concrete event.
     pub fn is<E: Event + 'static>(&self) -> bool {
         self.inner.is::<E>()
     }
 }
 
+/// A marker trait which all events must implement.
 pub trait Event: Any + Debug {}

src/jid.rs

@@ -1,3 +1,5 @@
+//! Provides a type for Jabber IDs.
+
 use std::fmt;
 
 use std::convert::Into;

src/plugin.rs

@@ -1,3 +1,5 @@
+//! Provides the plugin infrastructure.
+
 use event::{Event, AbstractEvent};
 
 use std::any::Any;