update micro_http documentation

Signed-off-by: George Pisaltu <gpl@amazon.com>

Author: georgepisaltu

micro_http/src/connection.rs

@@ -71,6 +71,11 @@ impl<T: Read + Write> HttpConnection<T> {
     /// Tries to read new bytes from the stream and automatically update the request.
     /// Meant to be used only with non-blocking streams and an `EPOLL` structure.
     /// Should be called whenever an `EPOLLIN` event is signaled.
+    ///
+    /// # Errors
+    /// `StreamError` is returned when an IO operation fails.
+    /// `ConnectionClosed` is returned when a client prematurely closes the connection.
+    /// `ParseError` is returned when a parsing operation fails.
     pub fn try_read(&mut self) -> Result<(), ConnectionError> {
         // Read some bytes from the stream, which will be appended to what is already
         // present in the buffer from a previous call of `try_read`. There are already
@@ -293,6 +298,12 @@ impl<T: Read + Write> HttpConnection<T> {
     /// Tries to write the first available response to the provided stream.
     /// Meant to be used only with non-blocking streams and an `EPOLL` structure.
     /// Should be called whenever an `EPOLLOUT` event is signaled.
+    ///
+    /// # Errors
+    /// `StreamError` is returned when an IO operation fails.
+    /// `ConnectionClosed` is returned when trying to write on a closed connection.
+    /// `InvalidWrite` is returned when trying to write on a connection with an
+    /// empty outgoing buffer.
     pub fn try_write(&mut self) -> Result<(), ConnectionError> {
         if self.response_buffer.is_none() {
             if let Some(response) = self.response_queue.pop_front() {
@@ -365,12 +376,13 @@ impl<T: Read + Write> HttpConnection<T> {
         self.read_cursor = end_cursor - line_start_index;
     }
 
-    /// Returns the first parsed request in the queue.
+    /// Returns the first parsed request in the queue or `None` if the queue
+    /// is empty.
     pub fn pop_parsed_request(&mut self) -> Option<Request> {
         self.parsed_requests.pop_front()
     }
 
-    /// Returns true if there are bytes waiting to be written into the stream.
+    /// Returns `true` if there are bytes waiting to be written into the stream.
     pub fn pending_write(&self) -> bool {
         self.response_buffer.is_some() || !self.response_queue.is_empty()
     }

micro_http/src/lib.rs

@@ -56,11 +56,12 @@
 //! ## Example for creating an HTTP Response
 //! ```
 //! extern crate micro_http;
-//! use micro_http::{Body, Response, StatusCode, Version};
+//! use micro_http::{Body, Response, StatusCode, Version, MediaType};
 //!
 //! let mut response = Response::new(Version::Http10, StatusCode::OK);
 //! let body = String::from("This is a test");
 //! response.set_body(Body::new(body.clone()));
+//! response.set_content_type(MediaType::PlainText);
 //!
 //! assert!(response.status() == StatusCode::OK);
 //! assert_eq!(response.body().unwrap(), Body::new(body));

micro_http/src/server.rs

@@ -32,7 +32,7 @@ pub struct ServerRequest {
 }
 
 impl ServerRequest {
-    /// Creates a new `RequestWithID` object from an existing `Request`,
+    /// Creates a new `ServerRequest` object from an existing `Request`,
     /// adding an identification token.
     pub fn new(request: Request, id: u64) -> Self {
         ServerRequest { request, id }
@@ -43,7 +43,10 @@ impl ServerRequest {
         &self.request
     }
 
-    /// Docs needed.
+    /// Calls the function provided on the inner request to obtain the response.
+    /// The response is then wrapped in a `ServerResponse`.
+    ///
+    /// Returns a `ServerResponse` ready for yielding to the server
     pub fn process<F>(&self, callable: F) -> ServerResponse
     where
         F: Fn(&Request) -> Response,
@@ -246,6 +249,12 @@ pub struct HttpServer {
 
 impl HttpServer {
     /// Constructor for `HttpServer`.
+    ///
+    /// Returns the newly formed `HttpServer`.
+    ///
+    /// # Errors
+    /// Returns an `IOError` when binding or `epoll::create` fails.
+    ///
     pub fn new<P: AsRef<Path>>(path_to_socket: P) -> Result<Self> {
         let socket = UnixListener::bind(path_to_socket).map_err(ServerError::IOError)?;
         let epoll_fd = epoll::create(true).map_err(ServerError::IOError)?;
@@ -273,6 +282,13 @@ impl HttpServer {
     ///
     /// Returns a collection of complete and valid requests to be processed by the user
     /// of the server. Once processed, responses should be sent using `enqueue_responses()`.
+    ///
+    /// # Errors
+    /// `IOError` is returned when `read`, `write` or `epoll::ctl` operations fail.
+    /// `ServerFull` is returned when a client is trying to connect to the server, but
+    /// full capacity has already been reached.
+    /// `InvalidWrite` is returned when the server attempted to perform a write operation
+    /// on a connection on which it is not possible.
     pub fn incoming(&mut self) -> Result<Vec<ServerRequest>> {
         let mut parsed_requests: Vec<ServerRequest> = vec![];
         let mut events = vec![epoll::Event::new(epoll::Events::empty(), 0); MAX_CONNECTIONS];
@@ -353,12 +369,69 @@ impl HttpServer {
         Ok(parsed_requests)
     }
 
+    /// The file descriptor of the `epoll` structure can enable the server to become
+    /// a non-blocking structure in an application.
+    ///
     /// Returns the file descriptor of the server's internal `epoll` structure.
+    ///
+    /// # Example
+    ///
+    /// ## Non-blocking server
+    /// ```
+    /// extern crate epoll;
+    ///
+    /// use micro_http::{HttpServer, Response, StatusCode};
+    ///
+    /// // Create our epoll manager.
+    /// let epoll_fd = epoll::create(true).unwrap();
+    ///
+    /// let path_to_socket = "/tmp/epoll_example.sock";
+    /// std::fs::remove_file(path_to_socket).unwrap_or_default();
+    ///
+    /// // Start the server.
+    /// let mut server = HttpServer::new(path_to_socket).unwrap();
+    /// server.start_server().unwrap();
+    ///
+    /// // Add our server to the `epoll` manager.
+    /// epoll::ctl(
+    ///            epoll_fd,
+    ///            epoll::ControlOptions::EPOLL_CTL_ADD,
+    ///            server.epoll_fd(),
+    ///            epoll::Event::new(epoll::Events::EPOLLIN, 1234u64),
+    ///        ).unwrap();
+    ///
+    /// // Connect a client to the server so it doesn't block in our example.
+    /// let mut socket = std::os::unix::net::UnixStream::connect(path_to_socket).unwrap();
+    ///
+    /// // Control loop of the application.
+    /// let mut events = Vec::with_capacity(10);
+    /// loop {
+    ///     let num_ev = epoll::wait(epoll_fd, -1, events.as_mut_slice());
+    ///     for event in events {
+    ///         match event.data {
+    ///             // The server notification.
+    ///             1234 => {
+    ///                 let request = server.incoming();
+    ///                 // Process...
+    ///             },
+    ///             // Other `epoll` notifications.
+    ///             _ => {
+    ///                 // Do other computation.
+    ///             },
+    ///         }
+    ///     }
+    ///     // Break this example loop.
+    ///     break;
+    /// }
+    /// ```
     pub fn epoll_fd(&self) -> RawFd {
         self.epoll_fd
     }
 
     /// Enqueues the provided responses in the outgoing connection.
+    ///
+    /// # Errors
+    /// `IOError` is returned when an `epoll::ctl` operation fails.
     pub fn enqueue_responses(&mut self, responses: Vec<ServerResponse>) -> Result<()> {
         for response in responses {
             self.respond(response)?;
@@ -367,7 +440,10 @@ impl HttpServer {
         Ok(())
     }
 
-    /// Docs needed.
+    /// Adds the provided response to the outgoing buffer in the corresponding connection.
+    ///
+    /// # Errors
+    /// `IOError` is returned when an `epoll::ctl` operation fails.
     pub fn respond(&mut self, response: ServerResponse) -> Result<()> {
         if let Some(client_connection) = self.connections.get_mut(&(response.id as i32)) {
             // If the connection was incoming before we enqueue the response, we change its
@@ -382,6 +458,9 @@ impl HttpServer {
     }
 
     /// Accepts a new incoming connection and adds it to the `epoll` notification structure.
+    ///
+    /// # Errors
+    /// `IOError` is returned when an `epoll::ctl` operation fails.
     fn handle_new_connection(&mut self) -> Result<()> {
         if self.connections.len() == MAX_CONNECTIONS {
             // If we want a replacement policy for connections