Merge pull request #129 from Jebes/master

Added documentation to varint.h and util.h

.gitignore

@@ -1,7 +1,23 @@
 .DS_Store
+/doc
 /build
 /tags
 
 # vim swap files
 *.swp
 *.swo
+TAGS
+!TAGS/
+tags
+!tags/
+gtags.files
+GTAGS
+GRTAGS
+GPATH
+cscope.files
+cscope.out
+cscope.in.out
+cscope.po.out
+
+
+

src/common/util.cpp

@@ -47,7 +47,7 @@ using namespace epee;
 
 namespace tools
 {
-  std::function<void(void)> signal_handler::m_handler;
+  std::function<void(void)> signal_handler::m_handler; 
 
 #ifdef WIN32
   std::string get_windows_version_display_string()
@@ -313,17 +313,19 @@ std::string get_nix_version_display_string()
     return "";
   }
 #endif
-
+  
   std::string get_default_data_dir()
   {
-    //namespace fs = boost::filesystem;
+    /* Please for the love of god refactor  the ifdefs out of this */
+
+    // namespace fs = boost::filesystem;
     // Windows < Vista: C:\Documents and Settings\Username\Application Data\CRYPTONOTE_NAME
     // Windows >= Vista: C:\Users\Username\AppData\Roaming\CRYPTONOTE_NAME
     // Mac: ~/Library/Application Support/CRYPTONOTE_NAME
     // Unix: ~/.CRYPTONOTE_NAME
     std::string config_folder;
+
 #ifdef WIN32
-    // Windows
     config_folder = get_special_folder_path(CSIDL_APPDATA, true) + "/" + CRYPTONOTE_NAME;
 #else
     std::string pathRet;

src/common/util.h

@@ -39,11 +39,41 @@
 #include "misc_language.h"
 #include "p2p/p2p_protocol_defs.h"
 
+/*! \brief Various Tools
+ *
+ *  
+ * 
+ */
 namespace tools
 {
+  /*! \brief Returns the default data directory.
+   *
+   * \details Windows < Vista: C:\\Documents and Settings\\Username\\Application Data\\CRYPTONOTE_NAME
+   *
+   * Windows >= Vista: C:\\Users\\Username\\AppData\\Roaming\\CRYPTONOTE_NAME
+   *
+   * Mac: ~/Library/Application Support/CRYPTONOTE_NAME
+   *
+   * Unix: ~/.CRYPTONOTE_NAME
+   */
   std::string get_default_data_dir();
+
+  /*! \brief Returns the OS version string
+   *
+   * \details This is a wrapper around the primitives
+   * get_windows_version_display_string() and
+   * get_nix_version_display_string()
+   */
   std::string get_os_version_string();
+
+  /*! \brief creates directories for a path
+   *
+   *  wrapper around boost::filesyste::create_directories.  
+   *  (ensure-directory-exists): greenspun's tenth rule in action!
+   */
   bool create_directories_if_necessary(const std::string& path);
+  /*! \brief std::rename wrapper for nix and something strange for windows.
+   */
   std::error_code replace_file(const std::string& replacement_name, const std::string& replaced_name);
 
   inline crypto::hash get_proof_of_trust_hash(const nodetool::proof_of_trust& pot)
@@ -54,10 +84,12 @@ namespace tools
     return crypto::cn_fast_hash(s.data(), s.size());
   }
 
-
+  /*! \brief Defines a signal handler for win32 and *nix
+   */
   class signal_handler
   {
   public:
+    /*! \brief installs a signal handler  */
     template<typename T>
     static bool install(T t)
     {
@@ -69,6 +101,7 @@ namespace tools
       }
       return r;
 #else
+      /* Only blocks SIGINT and SIGTERM */
       signal(SIGINT, posix_handler);
       signal(SIGTERM, posix_handler);
       m_handler = t;
@@ -78,12 +111,12 @@ namespace tools
 
   private:
 #if defined(WIN32)
+    /*! \brief Handler for win */
     static BOOL WINAPI win_handler(DWORD type)
     {
       if (CTRL_C_EVENT == type || CTRL_BREAK_EVENT == type)
       {
         handle_signal();
-        return TRUE;
       }
       else
       {
@@ -93,12 +126,14 @@ namespace tools
       return TRUE;
     }
 #else
+    /*! \brief handler for NIX */
     static void posix_handler(int /*type*/)
     {
       handle_signal();
     }
 #endif
 
+    /*! \brief calles m_handler */
     static void handle_signal()
     {
       static std::mutex m_mutex;
@@ -106,7 +141,7 @@ namespace tools
       m_handler();
     }
 
-  private:
+    /*! \brief where the installed handler is stored */
     static std::function<void(void)> m_handler;
   };
 }

src/common/varint.h

@@ -35,54 +35,94 @@
 #include <utility>
 #include <sstream>
 #include <string>
+/*! \file varint.h
+ * \breif provides the implementation of varint's
+ * 
+ * The representation of varints is rather odd. The first bit of each
+ * octet is significant, it represents wheter there is another part
+ * waiting to be read. For example 0x8002 would return 0x200, even
+ * though 0x02 does not have its msb set. The actual way they are read
+ * is as follows: Strip the msb of each byte, then from left to right,
+ * read in what remains, placing it in reverse, into the buffer. Thus,
+ * the following bit stream: 0xff02 would return 0x027f. 0xff turns
+ * into 0x7f, is placed on the beggining of the buffer, then 0x02 is
+ * unchanged, since its msb is not set, and placed at the end of the
+ * buffer.
+ */
 
 namespace tools {
 
-    template<typename OutputIt, typename T>
-    typename std::enable_if<std::is_integral<T>::value && std::is_unsigned<T>::value, void>::type
-    write_varint(OutputIt &&dest, T i) {
-        while (i >= 0x80) {
-            *dest++ = (static_cast<char>(i) & 0x7f) | 0x80;
-            i >>= 7;
-        }
-        *dest++ = static_cast<char>(i);
-    }
+  /*! \brief Error codes for varint
+   */
+  enum {
+    /* \brief Represents the overflow error */
+    EVARINT_OVERFLOW = -1,
+    /* \brief Represents a non conical represnetation */
+    EVARINT_REPRESENT = -2,
+  };
 
-    template<typename t_type>
-    std::string get_varint_data(const t_type& v)
+  /*! \brief writes a varint to a stream.
+   */
+  template<typename OutputIt, typename T>
+  /* Requires T to be both an integral type and unsigned, should be a compile error if it is not */
+  typename std::enable_if<std::is_integral<T>::value && std::is_unsigned<T>::value, void>::type 
+  write_varint(OutputIt &&dest, T i) {
+    /* Make sure that there is one after this */
+    while (i >= 0x80) {
+      *dest = (static_cast<char>(i) & 0x7f) | 0x80; 
+      ++dest;
+      i >>= 7;			/* I should be in multiples of 7, this should just get the next part */
+    }
+    /* writes the last one to dest */
+    *dest = static_cast<char>(i);
+    dest++;			/* Seems kinda pointless... */
+  }
+
+  /*! \brief Returns the string that represents the varint
+   */
+  template<typename T>
+    std::string get_varint_data(const T& v)
     {
       std::stringstream ss;
       write_varint(std::ostreambuf_iterator<char>(ss), v);
       return ss.str();
     }
-
-    template<int bits, typename InputIt, typename T>
+  /*! \brief reads in the varint that is pointed to by InputIt into write
+   */ 
+  template<int bits, typename InputIt, typename T>
     typename std::enable_if<std::is_integral<T>::value && std::is_unsigned<T>::value && 0 <= bits && bits <= std::numeric_limits<T>::digits, int>::type
-    read_varint(InputIt &&first, InputIt &&last, T &i) {
-        int read = 0;
-        i = 0;
-        for (int shift = 0;; shift += 7) {
-            if (first == last) {
-                return read; // End of input.
-            }
-            unsigned char byte = *first++;
-            ++read;
-            if (shift + 7 >= bits && byte >= 1 << (bits - shift)) {
-                return -1; // Overflow.
-            }
-            if (byte == 0 && shift != 0) {
-                return -2; // Non-canonical representation.
-            }
-            i |= static_cast<T>(byte & 0x7f) << shift;
-            if ((byte & 0x80) == 0) {
-                break;
-            }
-        }
-        return read;
-    }
+    read_varint(InputIt &&first, InputIt &&last, T &write) {
+    int read = 0;
+    write = 0;
+    for (int shift = 0;; shift += 7) {
+      if (first == last) {
+	return read; 
+      }
+      unsigned char byte = *first;
+      ++first;
+      ++read;
+      if (shift + 7 >= bits && byte >= 1 << (bits - shift)) {
+	return EVARINT_OVERFLOW;
+      }
+      if (byte == 0 && shift != 0) {
+	return EVARINT_REPRESENT;
+      }
 
-    template<typename InputIt, typename T>
-    int read_varint(InputIt &&first, InputIt &&last, T &i) {
-        return read_varint<std::numeric_limits<T>::digits, InputIt, T>(std::move(first), std::move(last), i);
+      write |= static_cast<T>(byte & 0x7f) << shift; /* Does the actualy placing into write, stripping the first bit */
+
+      /* If there is no next */
+      if ((byte & 0x80) == 0) {
+	break;
+      }
     }
+    return read;
+  }
+
+  /*! \brief Wrapper around the other read_varint,
+   *  Sets template parameters for you.
+   */
+  template<typename InputIt, typename T>
+    int read_varint(InputIt &&first, InputIt &&last, T &i) {
+    return read_varint<std::numeric_limits<T>::digits, InputIt, T>(std::move(first), std::move(last), i);
+  }
 }

src/daemon/daemon.cpp

@@ -29,7 +29,7 @@
 // Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers
 
 // node.cpp : Defines the entry point for the console application.
-//
+// Does this file exist?
 
 
 #include "include_base_utils.h"
@@ -64,11 +64,42 @@ namespace
   const command_line::arg_descriptor<bool>        arg_console     = {"no-console", "Disable daemon console commands"};
 }
 
-bool command_line_preprocessor(const boost::program_options::variables_map& vm);
+bool command_line_preprocessor(const boost::program_options::variables_map& vm)
+{
+  bool exit = false;
+  if (command_line::get_arg(vm, command_line::arg_version))
+  {
+    std::cout << CRYPTONOTE_NAME  << " v" << PROJECT_VERSION_LONG << ENDL;
+    exit = true;
+  }
+  if (command_line::get_arg(vm, arg_os_version))
+  {
+    std::cout << "OS: " << tools::get_os_version_string() << ENDL;
+    exit = true;
+  }
+
+  if (exit)
+  {
+    return true;
+  }
+
+  int new_log_level = command_line::get_arg(vm, arg_log_level);
+  if(new_log_level < LOG_LEVEL_MIN || new_log_level > LOG_LEVEL_MAX)
+  {
+    LOG_PRINT_L0("Wrong log level value: ");
+  }
+  else if (log_space::get_set_log_detalisation_level(false) != new_log_level)
+  {
+    log_space::get_set_log_detalisation_level(true, new_log_level);
+    LOG_PRINT_L0("LOG_LEVEL set to " << new_log_level);
+  }
+
+  return false;
+}
 
 int main(int argc, char* argv[])
 {
-
+  
   string_tools::set_module_name_and_folder(argv[0]);
 #ifdef WIN32
   _CrtSetDbgFlag ( _CRTDBG_ALLOC_MEM_DF | _CRTDBG_LEAK_CHECK_DF );
@@ -235,35 +266,3 @@ int main(int argc, char* argv[])
   CATCH_ENTRY_L0("main", 1);
 }
 
-bool command_line_preprocessor(const boost::program_options::variables_map& vm)
-{
-  bool exit = false;
-  if (command_line::get_arg(vm, command_line::arg_version))
-  {
-    std::cout << CRYPTONOTE_NAME  << " v" << PROJECT_VERSION_LONG << ENDL;
-    exit = true;
-  }
-  if (command_line::get_arg(vm, arg_os_version))
-  {
-    std::cout << "OS: " << tools::get_os_version_string() << ENDL;
-    exit = true;
-  }
-
-  if (exit)
-  {
-    return true;
-  }
-
-  int new_log_level = command_line::get_arg(vm, arg_log_level);
-  if(new_log_level < LOG_LEVEL_MIN || new_log_level > LOG_LEVEL_MAX)
-  {
-    LOG_PRINT_L0("Wrong log level value: ");
-  }
-  else if (log_space::get_set_log_detalisation_level(false) != new_log_level)
-  {
-    log_space::get_set_log_detalisation_level(true, new_log_level);
-    LOG_PRINT_L0("LOG_LEVEL set to " << new_log_level);
-  }
-
-  return false;
-}

src/daemon/daemon_commands_handler.h

@@ -28,6 +28,8 @@
 // 
 // Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers
 
+
+/* This isn't a header file, may want to refactor this... */
 #pragma once
 
 #include <boost/lexical_cast.hpp>
@@ -39,7 +41,11 @@
 #include "crypto/hash.h"
 #include "version.h"
 
-
+/*!
+ * \brief I don't really know right now
+ *  
+ * 
+ */
 class daemon_cmmands_handler
 {
   nodetool::node_server<cryptonote::t_cryptonote_protocol_handler<cryptonote::core> >& m_srv;