update docs

src/httpmessage.rs

@@ -146,9 +146,14 @@ impl HttpRequest {
         &mut self.headers
     }
 
+    /// Get a reference to the Params object.
+    /// Params is a container for url parameters.
+    /// Route supports glob patterns: * for a single wildcard segment and :param
+    /// for matching storing that segment of the request url in the Params object.
     #[inline]
     pub fn params(&self) -> &Params { &self.params }
 
+    /// Create new request with Params object.
     pub fn with_params(self, params: Params) -> Self {
         HttpRequest {
             method: self.method,
@@ -159,7 +164,7 @@ impl HttpRequest {
         }
     }
 
-    pub fn is_upgrade(&self) -> bool {
+    pub(crate) fn is_upgrade(&self) -> bool {
         if let Some(&Connection(ref conn)) = self.headers().get() {
             conn.contains(&ConnectionOption::from_str("upgrade").unwrap())
         } else {

src/lib.rs

@@ -43,5 +43,5 @@ pub use resource::{HttpMessage, HttpResource};
 pub use server::HttpServer;
 pub use context::HttpContext;
 pub use router::RoutingMap;
-pub use route_recognizer::Params;
 pub use httpmessage::{HttpRequest, HttpResponse, IntoHttpResponse};
+pub use route_recognizer::Params;

src/resource.rs

@@ -11,7 +11,24 @@ use context::HttpContext;
 use httpcodes::HTTPMethodNotAllowed;
 use httpmessage::{HttpRequest, HttpResponse, IntoHttpResponse};
 
-/// Resource
+/// Http resource
+///
+/// `HttpResource` is an entry in route table which corresponds to requested URL.
+///
+/// Resource in turn has at least one route.
+/// Route corresponds to handling HTTP method by calling route handler.
+///
+/// ```rust,ignore
+///
+/// struct MyRoute;
+///
+/// fn main() {
+///     let mut routes = RoutingMap::default();
+///
+///     routes
+///      .add_resource("/")
+///         .post::<MyRoute>();
+/// }
 pub struct HttpResource<S=()> {
     state: PhantomData<S>,
     routes: HashMap<Method, Box<RouteHandler<S>>>,
@@ -91,6 +108,7 @@ enum HttpMessageItem<A> where A: Actor<Context=HttpContext<A>> + Route {
     Actor(A),
 }
 
+/// Represents response process.
 pub struct HttpMessage<A: Actor<Context=HttpContext<A>> + Route> (HttpMessageItem<A>);
 
 impl<A> HttpMessage<A> where A: Actor<Context=HttpContext<A>> + Route

src/route.rs

@@ -45,24 +45,32 @@ pub enum Frame {
     Payload(Option<Bytes>),
 }
 
+/// Trait defines object that could be regestered as resource route.
 pub trait RouteHandler<S>: 'static {
     fn handle(&self, req: HttpRequest, payload: Option<Payload>, state: Rc<S>) -> Task;
 }
 
 /// Actors with ability to handle http requests
 pub trait Route: Actor<Context=HttpContext<Self>> {
+    /// Route shared state. State is shared with all routes within same application and could be
+    /// accessed with `HttpContext::state()` method.
     type State;
 
+    /// Handle incoming request. Route actor can return
+    /// result immediately with `HttpMessage::reply` or `HttpMessage::error`.
+    /// Actor itself could be returned for handling streaming request/response.
+    /// In that case `HttpContext::start` and `HttpContext::write` hs to be used.
     fn request(req: HttpRequest,
                payload: Option<Payload>,
                ctx: &mut HttpContext<Self>) -> HttpMessage<Self>;
 
+    /// This method creates `RouteFactory` for this actor.
     fn factory() -> RouteFactory<Self, Self::State> {
         RouteFactory(PhantomData)
     }
 }
 
-
+/// This is used for routes registration within `HttpResource`.
 pub struct RouteFactory<A: Route<State=S>, S>(PhantomData<A>);
 
 impl<A, S> RouteHandler<S> for RouteFactory<A, S>

src/router.rs

@@ -14,6 +14,20 @@ pub trait HttpHandler: 'static {
     fn handle(&self, req: HttpRequest, payload: Option<Payload>) -> Task;
 }
 
+/// Request routing map
+///
+/// Route supports glob patterns: * for a single wildcard segment and :param
+/// for matching storing that segment of the request url in the Params object,
+/// which is stored in the request.
+///
+/// For instance, to route Get requests on any route matching /users/:userid/:friend and
+/// store userid and friend in the exposed Params object:
+///
+/// ```rust,ignore
+/// let mut router = RoutingMap::default();
+///
+/// router.add_resource("/users/:userid/:friendid").get::<MyRoute>();
+/// ```
 pub struct RoutingMap {
     apps: HashMap<String, Box<HttpHandler>>,
     resources: HashMap<String, HttpResource>,
@@ -30,20 +44,53 @@ impl Default for RoutingMap {
 
 impl RoutingMap {
 
-    pub fn add<P, S: 'static>(&mut self, path: P, app: HttpApplication<S>)
+    /// Add `HttpApplication` object with specific prefix.
+    /// Application prefixes all registered resources with specified prefix.
+    ///
+    /// ```rust,ignore
+    ///
+    /// struct MyRoute;
+    ///
+    /// fn main() {
+    ///     let mut app = HttpApplication::no_state();
+    ///     app.add("/test")
+    ///         .get::<MyRoute>()
+    ///         .post::<MyRoute>();
+    ///
+    ///     let mut routes = RoutingMap::default();
+    ///     routes.add("/pre", app);
+    /// }
+    /// ```
+    /// In this example, `MyRoute` route is available as `http://.../pre/test` url.
+    pub fn add<P, S: 'static>(&mut self, prefix: P, app: HttpApplication<S>)
         where P: ToString
     {
-        let path = path.to_string();
+        let prefix = prefix.to_string();
 
         // we can not override registered resource
-        if self.apps.contains_key(&path) {
-            panic!("Resource is registered: {}", path);
+        if self.apps.contains_key(&prefix) {
+            panic!("Resource is registered: {}", prefix);
         }
 
         // add application
-        self.apps.insert(path.clone(), app.prepare(path));
+        self.apps.insert(prefix.clone(), app.prepare(prefix));
     }
 
+    /// This method creates `HttpResource` for specified path
+    /// or returns mutable reference to resource object.
+    ///
+    /// ```rust,ignore
+    ///
+    /// struct MyRoute;
+    ///
+    /// fn main() {
+    ///     let mut routes = RoutingMap::default();
+    ///
+    ///     routes.add_resource("/test")
+    ///         .post::<MyRoute>();
+    /// }
+    /// ```
+    /// In this example, `MyRoute` route is available as `http://.../test` url.
     pub fn add_resource<P>(&mut self, path: P) -> &mut HttpResource
         where P: ToString
     {

src/ws.rs

@@ -103,6 +103,7 @@ header! {
 }
 
 
+/// `WebSocket` Message
 #[derive(Debug)]
 pub enum Message {
     Text(String),
@@ -116,7 +117,7 @@ pub enum Message {
 
 /// Prepare `WebSocket` handshake response.
 ///
-/// This function returns handshake HttpResponse, ready to send to peer.
+/// This function returns handshake `HttpResponse`, ready to send to peer.
 /// It does not perform any IO.
 ///
 // /// `protocols` is a sequence of known protocols. On successful handshake,