documentation

Author: shadrunov

src/client.cpp

@@ -1,3 +1,8 @@
+/**
+ * \file
+ * \brief Chat client -- interacts with user, displays, sends and encrypts messages
+**/
+
 #include "client_lib.hpp"
 #include <boost/asio.hpp>
 #include <boost/asio/buffer.hpp>
@@ -22,6 +27,11 @@ using json = nlohmann::json;
 
 void process_step(User &user)
 {   
+    /**
+    This function provides UI: 
+    draws screen and displays everything as well as performs navigation
+    \param user instance of User class
+    **/
     system("clear");
     std::string code;
 
@@ -31,12 +41,13 @@ void process_step(User &user)
 
         if (user.logged_in)
         {
-            fmt::print("Hi {}! \n\nSelect an option below:\n", user.username);
+            fmt::print("{}, welcome back! \n\nSelect an option below:\n", user.username);
             fmt::print(" s  |  Sync\n");
             fmt::print(" c  |  Chat List\n");
+            fmt::print("\nSync messages to get your inbox from the server. \nThen proceed to your Chat List.\n");
         } 
         else {
-            fmt::print("Welcome to Chat client! \n\nSelect an option below:\n");
+            fmt::print("Welcome to Chat client! \n\nEnter s, if you don't have an account or enter l to log in:\n");
             fmt::print(" u  |  Sign Up\n");
             fmt::print(" l  |  Log In\n");
         }
@@ -60,6 +71,7 @@ void process_step(User &user)
     else if (user.state == 1)  // sign up
     {
         fmt::print("Sign Up \n\n");
+        fmt::print("Welcome here! You are about to create an account. \nJust take any free username and you are ready to rock. \nAfter creating an account, go to Chat List section and \nstart new dialog. Sync messages after that.\n\n");
 
         while (!user.logged_in)  // ещё не зарегестрировался
         {
@@ -80,9 +92,10 @@ void process_step(User &user)
     else if (user.state == 2)  // log in
     {
         fmt::print("Log in \n\n");
+        fmt::print("Now you have to enter your username. If you are not registered yet, please,\ngo back and select Sign up. \n\n");
         while (!user.logged_in)  // ещё не вошёл
         {
-            fmt::print("Enter username (or b to go back): ");
+            fmt::print("Enter your username (or b to go back): ");
             std::getline(std::cin >> std::ws, code);
             if (code == std::string{'b'}) { user.state = 0; break;}
 
@@ -98,7 +111,7 @@ void process_step(User &user)
 
     else if (user.state == 3)  // sync
     {
-        fmt::print("Sync messages... \n\n");
+        fmt::print("Syncing messages... \n\n");
 
         user.messages = get_messages(user);
         user.state = 0;
@@ -115,7 +128,7 @@ void process_step(User &user)
             [&](){
                 system("clear");
                 fmt::print("Chat List \n\nSelect from the list below: \n\n");
-                if (user.messages.empty()) fmt::print("Empty. Try to sync messages first. \n\n");
+                if (user.messages.empty()) fmt::print("Nothing's here. \nEnter n to start your first dialog! \nOr go back (b) and sync messages.\n\n");
                 else
                 {
                     // print out messages
@@ -158,9 +171,10 @@ void process_step(User &user)
 
     else if (user.state == 5)  // enter key
     {
-        fmt::print("Decrypt messages\n\nEnter the key from {} or b to go back: ", user.current_chat);
+        fmt::print("Decrypt messages\n\nIf you've just created chat, enter any word combination. \nYou will use it later to decrypt messages. \n\nEnter the key from {} or b to go back: ", user.current_chat);
         std::getline(std::cin >> std::ws, code);
-        if (code == std::string{'b'}) user.state = 0;
+        if (code == std::string{'b'}) 
+            user.state = 0;
         else 
         {
             user.current_key = code;
@@ -190,7 +204,7 @@ void process_step(User &user)
             std::string reply = encrypt(code, user.current_key);
             if (code == std::string{'b'}) break;
             if (send_reply(user.username, user.current_chat, reply)) 
-                fmt::print("Sent sucessfully. \n");
+                fmt::print("Sent. \n");
             else { 
                 fmt::print("Cannot send. \n\nenter b to go back>"); 
                 std::getline(std::cin >> std::ws, code);
@@ -205,7 +219,7 @@ void process_step(User &user)
         fmt::print("Start New Chat\n\n");
         while (user.state == 7)
         { 
-            fmt::print("Enter username: ");
+            fmt::print("Enter your friend's username: ");
             std::getline(std::cin >> std::ws, code);
             if (code == std::string{'b'}) { user.state = 0; break; }
             if (login(code)){  // проверяем что existed

src/client_lib.cpp

@@ -1,3 +1,8 @@
+/**
+ * \file
+ * \brief File implements functions from client_lib.hpp
+**/
+
 #include "client_lib.hpp"
 #include <nlohmann/json.hpp>
 #include <boost/asio.hpp>
@@ -11,6 +16,11 @@ using boost::asio::ip::tcp;
 
 bool is_valid_username(std::string username)
 {
+    /**
+    Checks if given username is correct (consists only from digits, letters and "_")
+    \param username given username
+    \return true if username is valid, false otherwise
+    **/
     for (char x : username)
         if ((std::isalnum(x) == 0) && (x != '_')) { return false; }  // bad character 
     return true;
@@ -19,6 +29,12 @@ bool is_valid_username(std::string username)
 
 bool login(std::string username)
 {
+    /**
+    Checks if given username is correct and exists on server
+    \param username username of the user
+    \return true if username is valid and exists on server, false otherwise
+    **/
+
     if (!is_valid_username(username)) return false;
 
     boost::asio::io_service io_service;
@@ -38,6 +54,11 @@ bool login(std::string username)
 
 bool signup(std::string username)
 {
+    /**
+    Checks if given username is correct and then creates new user on server
+    \param username username of new user
+    \return true if username new user creates, false if not or if username is not correct
+    **/
     if (!is_valid_username(username)) return false;
 
     boost::asio::io_service io_service;
@@ -57,6 +78,36 @@ bool signup(std::string username)
 
 json get_messages(User &user)
 {
+    /**
+    Downloads messages addressed to current user from server
+    \param user instance of User class
+    \return json with messages
+    \code json
+    get bob
+    {
+        "alice": {
+            "0": {
+                "receiver": "alice",
+                "sender": "bob",
+                "text": "q2ZJuWt="
+            },
+            "1": {
+                "receiver": "alice",
+                "sender": "bob",
+                "text": "riY="
+            }
+        },
+        "mike": {
+            "0": {
+                "receiver": "bob",
+                "sender": "mike",
+                "text": "rh5Ggq3GhzUXe2QxvU=="
+            }
+        }
+    }
+    \endcode
+    **/
+
     boost::asio::io_service io_service;
     tcp::socket socket(io_service);
     socket.connect(tcp::endpoint(boost::asio::ip::address::from_string(ip), port));
@@ -74,6 +125,13 @@ json get_messages(User &user)
 
 bool send_reply(std::string &sender, std::string &receiver, std::string &text)
 {
+    /**
+    Sends message to server
+    \param sender username of current user
+    \param receiver username of recipient
+    \param text string with encrypted text of the message
+    \return true if successful
+    **/
     boost::asio::io_service io_service;
     tcp::socket socket(io_service);
     socket.connect(tcp::endpoint(boost::asio::ip::address::from_string(ip), port));
@@ -89,4 +147,5 @@ bool send_reply(std::string &sender, std::string &receiver, std::string &text)
     std::string response{boost::asio::buffer_cast<const char*>(rb.data())};
 
     return (response == "200\n");
-}
+}
+

src/client_lib.hpp

@@ -1,3 +1,8 @@
+/**
+ * \file
+ * \brief File defines functions and a structure for chat client
+**/
+
 #include <iostream>
 #include <string>
 #include <nlohmann/json.hpp>
@@ -7,29 +12,79 @@ using json = nlohmann::json;
 const std::string ip = "127.0.0.1";
 const int port = 1234;
 
-
+/**
+    Checks if given username is correct (consists only from digits, letters and "_")
+    \param username given username
+    \return true if username is valid, false otherwise
+**/
 bool is_valid_username(std::string username);
 
+
 struct User
 {
-    size_t state = 0;  // current position
-    bool logged_in = false;
-    std::string username;
+    /**
+     * stores data of current user
+    **/
+    size_t state = 0;  ///< current position of user (current screen)
+    bool logged_in = false;  ///< if user is logged in
+    std::string username;  ///< username of the user
 
-    json messages;
+    json messages;  ///< stores messages downloaded from server
 
-    std::string current_chat;
-    std::string current_key;
+    std::string current_chat;  ///< username of current chat
+    std::string current_key;  ///< crypto key of current chat
 };
 
-
+/**
+    Checks if given username is correct and exists on server
+    \param username username of the user
+    \return true if username is valid and exists on server, false otherwise
+**/
 bool login(std::string username);
 
-
+/**
+    Checks if given username is correct and then creates new user on server
+    \param username username of new user
+    \return true if username new user creates, false if not or if username is not correct
+**/
 bool signup(std::string username);
 
-
+/**
+    Downloads messages addressed to current user from server
+    \param user instance of User class
+    \return json with messages
+    \code json
+    get bob
+    {
+        "alice": {
+            "0": {
+                "receiver": "alice",
+                "sender": "bob",
+                "text": "q2ZJuWt="
+            },
+            "1": {
+                "receiver": "alice",
+                "sender": "bob",
+                "text": "riY="
+            }
+        },
+        "mike": {
+            "0": {
+                "receiver": "bob",
+                "sender": "mike",
+                "text": "rh5Ggq3GhzUXe2QxvU=="
+            }
+        }
+    }
+    \endcode
+**/
 json get_messages(User &user);
 
-
+/**
+    Sends message to server
+    \param sender username of current user
+    \param receiver username of recipient
+    \param text string with encrypted text of the message
+    \return true if successful
+**/
 bool send_reply(std::string &sender, std::string &receiver, std::string &text);

src/server.cpp

@@ -1,3 +1,13 @@
+/**
+ * \file
+ * \brief Chat server -- stores users and messages
+ * supports 4 methods:
+ * - login <username>
+ * - signup <username>
+ * - get <username>
+ * - send <sender> <receiver> <text of a message>
+**/
+
 //
 // echo_server.cpp
 // ~~~~~~~~~~~~~~~