From ea646f63549ac055ef471997b4fd3f7bb1729728 Mon Sep 17 00:00:00 2001
From: Erik Zandvliet <erik.zandvliet@ddvtech.com>
Date: Thu, 28 Mar 2013 16:14:13 +0100
Subject: [PATCH] Added doxygen-style documentation to the controller.

---
 src/controller/controller.cpp              | 28 ++++++++++++++++------
 src/controller/controller_capabilities.cpp | 20 +++++++++++-----
 src/controller/controller_connectors.cpp   | 17 +++++++------
 src/controller/controller_storage.cpp      |  9 +++++--
 src/controller/controller_streams.cpp      |  1 +
 5 files changed, 53 insertions(+), 22 deletions(-)

diff --git a/src/controller/controller.cpp b/src/controller/controller.cpp
index 41b8f4d3..74e9fd51 100644
--- a/src/controller/controller.cpp
+++ b/src/controller/controller.cpp
@@ -23,18 +23,23 @@
 #define COMPILED_PASSWORD ""
 #endif
 
+///\brief Holds everything unique to the controller.
 namespace Controller {
 
   Secure::Auth keychecker; ///< Checks key authorization.
 
+  ///\brief A class storing information about a connected user.
   class ConnectedUser{
     public:
-      Socket::Connection C;
-      HTTP::Parser H;
-      bool Authorized;
-      bool clientMode;
-      int logins;
-      std::string Username;
+      Socket::Connection C;///<The socket through which the user is connected.
+      HTTP::Parser H;///<The HTTP::Parser associated to this user, for the lsp.
+      bool Authorized;///<Indicates whether the current user is authorized.
+      bool clientMode;///<Indicates how to parse the commands.
+      int logins;///<Keeps track of the amount of login-tries.
+      std::string Username;///<The username of the user.
+      
+      ///\brief Construct a new user from a connection.
+      ///\param c The socket through which the user is connected.
       ConnectedUser(Socket::Connection c){
         C = c;
         H.Clean();
@@ -44,6 +49,10 @@ namespace Controller {
       }
   };
 
+  ///\brief Checks an authorization request for a given user.
+  ///\param Request The request to be parsed.
+  ///\param Response The location to store the generated response.
+  ///\param conn The user to be checked for authorization.
   void Authorize(JSON::Value & Request, JSON::Value & Response, ConnectedUser & conn){
     time_t Time = time(0);
     tm * TimeInfo = localtime( &Time);
@@ -76,6 +85,9 @@ namespace Controller {
     return;
   }
 
+  ///\brief Check the submitted configuration and handle things accordingly.
+  ///\param in The new configuration.
+  ///\param out The location to store the resulting configuration.
   void CheckConfig(JSON::Value & in, JSON::Value & out){
     for (JSON::ObjIter jit = in.ObjBegin(); jit != in.ObjEnd(); jit++){
       if (jit->first == "version"){
@@ -99,6 +111,8 @@ namespace Controller {
     out = in;
   }
 
+  ///\brief Parse received statistics.
+  ///\param stats The statistics to be parsed.
   void CheckStats(JSON::Value & stats){
     long long int currTime = Util::epoch();
     for (JSON::ObjIter jit = stats.ObjBegin(); jit != stats.ObjEnd(); jit++){
@@ -121,9 +135,9 @@ namespace Controller {
       }
     }
   }
-
 } //Controller namespace
 
+///\brief The main entry point for the controller.
 int main(int argc, char ** argv){
   Controller::Storage = JSON::fromFile("config.json");
   JSON::Value stored_port = JSON::fromString("{\"long\":\"port\", \"short\":\"p\", \"arg\":\"integer\", \"help\":\"TCP port to listen on.\"}");
diff --git a/src/controller/controller_capabilities.cpp b/src/controller/controller_capabilities.cpp
index 7552d1cc..0c7f8d55 100644
--- a/src/controller/controller_capabilities.cpp
+++ b/src/controller/controller_capabilities.cpp
@@ -4,15 +4,18 @@
 #include <set>
 #include "controller_capabilities.h"
 
+///\brief Holds everything unique to the controller.
 namespace Controller {
-
+  ///\brief A class storing information about the cpu the server is running on.
   class cpudata{
     public:
-      std::string model;
-      int cores;
-      int threads;
-      int mhz;
-      int id;
+      std::string model;///<A string describing the model of the cpu.
+      int cores;///<The amount of cores in the cpu.
+      int threads;///<The amount of threads this cpu can run.
+      int mhz;///<The speed of the cpu in mhz.
+      int id;///<The id of the cpu in the system.
+      
+      ///\brief The default constructor
       cpudata(){
         model = "Unknown";
         cores = 1;
@@ -21,6 +24,9 @@ namespace Controller {
         id = 0;
       }
       ;
+      
+      ///\brief Fills the structure by parsing a given description.
+      ///\param data A description of the cpu.
       void fill(char * data){
         int i;
         i = 0;
@@ -43,6 +49,8 @@ namespace Controller {
       ;
   };
 
+  ///\brief Checks the capabilities of the system.
+  ///\param capa The location to store the capabilities.
   void checkCapable(JSON::Value & capa){
     capa.null();
     std::ifstream cpuinfo("/proc/cpuinfo");
diff --git a/src/controller/controller_connectors.cpp b/src/controller/controller_connectors.cpp
index 67d30c84..5482b296 100644
--- a/src/controller/controller_connectors.cpp
+++ b/src/controller/controller_connectors.cpp
@@ -5,14 +5,16 @@
 #include "controller_storage.h"
 #include "controller_connectors.h"
 
+///\brief Holds everything unique to the controller.
 namespace Controller {
 
-  static std::map<std::string, std::string> current_connectors;
+  static std::map<std::string, std::string> currentConnectors; ///<The currently running connectors.
 
-  /// Checks if the binary mentioned in the protocol argument is currently active, if so, restarts it.
+  ///\brief Checks if the binary mentioned in the protocol argument is currently active, if so, restarts it.
+  ///\param protocol The protocol to check.
   void UpdateProtocol(std::string protocol){
     std::map<std::string, std::string>::iterator iter;
-    for (iter = current_connectors.begin(); iter != current_connectors.end(); iter++){
+    for (iter = currentConnectors.begin(); iter != currentConnectors.end(); iter++){
       if (iter->second.substr(0, protocol.size()) == protocol){
         Log("CONF", "Restarting connector for update: " + iter->second);
         Util::Procs::Stop(iter->first);
@@ -30,7 +32,8 @@ namespace Controller {
     }
   }
 
-  /// Checks current protocol configuration, updates state of enabled connectors if neccesary.
+  ///\brief Checks current protocol configuration, updates state of enabled connectors if neccesary.
+  ///\param p An object containing all protocols.
   void CheckProtocols(JSON::Value & p){
     std::map<std::string, std::string> new_connectors;
     std::map<std::string, std::string>::iterator iter;
@@ -79,7 +82,7 @@ namespace Controller {
     }
 
     //shut down deleted/changed connectors
-    for (iter = current_connectors.begin(); iter != current_connectors.end(); iter++){
+    for (iter = currentConnectors.begin(); iter != currentConnectors.end(); iter++){
       if (new_connectors.count(iter->first) != 1 || new_connectors[iter->first] != iter->second){
         Log("CONF", "Stopping connector: " + iter->second);
         Util::Procs::Stop(iter->first);
@@ -88,7 +91,7 @@ namespace Controller {
 
     //start up new/changed connectors
     for (iter = new_connectors.begin(); iter != new_connectors.end(); iter++){
-      if (current_connectors.count(iter->first) != 1 || current_connectors[iter->first] != iter->second || !Util::Procs::isActive(iter->first)){
+      if (currentConnectors.count(iter->first) != 1 || currentConnectors[iter->first] != iter->second || !Util::Procs::isActive(iter->first)){
         Log("CONF", "Starting connector: " + iter->second);
         Util::Procs::Start(iter->first, Util::getMyPath() + iter->second);
       }
@@ -102,7 +105,7 @@ namespace Controller {
     }
 
     //store new state
-    current_connectors = new_connectors;
+    currentConnectors = new_connectors;
   }
 
 }
diff --git a/src/controller/controller_storage.cpp b/src/controller/controller_storage.cpp
index e35af8c0..02085e3f 100644
--- a/src/controller/controller_storage.cpp
+++ b/src/controller/controller_storage.cpp
@@ -3,11 +3,14 @@
 #include <mist/timing.h>
 #include "controller_storage.h"
 
+///\brief Holds everything unique to the controller.
 namespace Controller {
 
   JSON::Value Storage; ///< Global storage of data.
 
-  /// Store and print a log message.
+  ///\brief Store and print a log message.
+  ///\param kind The type of message.
+  ///\param message The message to be logged.
   void Log(std::string kind, std::string message){
     //if last log message equals this one, do not log.
     if (Storage["log"].size() > 0){
@@ -25,7 +28,9 @@ namespace Controller {
     std::cout << "[" << kind << "] " << message << std::endl;
   }
 
-  /// Write contents to Filename
+  ///\brief Write contents to Filename
+  ///\param Filename The full path of the file to write to.
+  ///\param contents The data to be written to the file.
   void WriteFile(std::string Filename, std::string contents){
     std::ofstream File;
     File.open(Filename.c_str());
diff --git a/src/controller/controller_streams.cpp b/src/controller/controller_streams.cpp
index 4e9387a6..9aa5aea9 100644
--- a/src/controller/controller_streams.cpp
+++ b/src/controller/controller_streams.cpp
@@ -5,6 +5,7 @@
 #include "controller_storage.h"
 #include <sys/stat.h>
 
+///\brief Holds everything unique to the controller.
 namespace Controller {
 
   std::map<std::string, int> lastBuffer; ///< Last moment of contact with all buffers.