diff --git a/README.md b/README.md
index 866e143cd..5bdb88dd1 100644
--- a/README.md
+++ b/README.md
@@ -107,12 +107,9 @@ fn main() {
 
     HttpServer::new(
         Application::default("/")
-            // enable logger
-            .middleware(middlewares::Logger::default())
-            // websocket route
-            .resource("/ws/", |r| r.get(|req| ws::start(req, MyWebSocket)))
-            // static files
-            .route("/", StaticFiles::new("examples/static/", true)))
+            .middleware(middlewares::Logger::default())  // <- register logger middleware
+            .resource("/ws/", |r| r.get(|req| ws::start(req, MyWebSocket))) // <- websocket route
+            .route("/", StaticFiles::new("examples/static/", true))) // <- server static files
         .serve::<_, ()>("127.0.0.1:8080").unwrap();
 
     Arbiter::system().send(msgs::SystemExit(0));
diff --git a/src/ws.rs b/src/ws.rs
index faea7d08b..32bf49fb2 100644
--- a/src/ws.rs
+++ b/src/ws.rs
@@ -12,6 +12,7 @@
 //! use actix::*;
 //! use actix_web::*;
 //!
+//! // do websocket handshake and start actor
 //! fn ws_index(req: HttpRequest) -> Result<Reply> {
 //!     ws::start(req, WsRoute)
 //! }
@@ -40,7 +41,11 @@
 //!     }
 //! }
 //!
-//! fn main() {}
+//! fn main() {
+//!     Application::default("/")
+//!       .resource("/ws/", |r| r.get(ws_index))  // <- register websocket route
+//!       .finish();
+//! }
 //! ```
 use std::vec::Vec;
 use http::{Method, StatusCode, header};
@@ -88,6 +93,7 @@ impl ResponseType for Message {
     type Error = ();
 }
 
+/// Do websocket handshake and start actor
 pub fn start<A, S>(mut req: HttpRequest<S>, actor: A) -> Result<Reply, Error>
     where A: Actor<Context=HttpContext<A, S>> + StreamHandler<Message>,
           S: 'static