From dec759a475102436e43d99e48adbecd1d55941f1 Mon Sep 17 00:00:00 2001
From: Titouan Rigoudy <titouan.rigoudy@gmail.com>
Date: Wed, 30 Mar 2016 19:43:57 +0200
Subject: [PATCH] Comment control::request and control::response.

---
 src/control/request.rs  | 10 ++++++++++
 src/control/response.rs | 16 ++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/src/control/request.rs b/src/control/request.rs
index 725b542..ab402ce 100644
--- a/src/control/request.rs
+++ b/src/control/request.rs
@@ -1,8 +1,18 @@
+/// This enumeration is the list of possible control requests made by the
+/// controller client to the client.
 #[derive(Debug, RustcDecodable, RustcEncodable)]
 pub enum Request {
+    /// Not a real request: this is to notify the client that a controller is
+    /// now connected, and control responses can now be sent.
     ConnectNotification,
+    /// Not a real request: this is to notify the client that the controller has
+    /// now disconnected, and control responses should no longer be
+    /// sent.
     DisconnectNotification,
+    /// The controller wants to join a room. Contains the room name.
     JoinRoomRequest(String),
+    /// The controller wants to know what the login status is.
     LoginStatusRequest,
+    /// The controller wants to know the list of visible chat rooms.
     RoomListRequest,
 }
diff --git a/src/control/response.rs b/src/control/response.rs
index da2dae2..0c571f1 100644
--- a/src/control/response.rs
+++ b/src/control/response.rs
@@ -1,29 +1,45 @@
 use room;
 
+/// This enumeration is the list of possible control responses from the client
+/// to the controller.
 #[derive(Debug, RustcDecodable, RustcEncodable)]
 pub enum Response {
     LoginStatusResponse(LoginStatusResponse),
     RoomListResponse(RoomListResponse),
 }
 
+/// This enumeration is the list of possible login states, and the associated
+/// information.
 #[derive(Debug, RustcDecodable, RustcEncodable)]
 pub enum LoginStatusResponse {
+    /// The login request has been sent to the server, but the response hasn't
+    /// been received yet.
     Pending {
+        /// The username used to log in.
         username: String,
     },
 
+    /// Login was successful.
     Success {
+        /// The username used to log in.
         username: String,
+        /// The message of the day sent by the server.
         motd: String,
     },
 
+    /// Login failed.
     Failure {
+        /// The username used to log in.
         username: String,
+        /// The reason the server gave for refusing the login request.
         reason: String,
     }
 }
 
+/// This structure contains the list of all visible rooms, and their associated
+/// data.
 #[derive(Debug, RustcDecodable, RustcEncodable)]
 pub struct RoomListResponse {
+    /// The list of (room name, room data) pairs.
     pub rooms: Vec<(String, room::Room)>,
 }