[Improvement] Docs (#17)

* Add documentation

CMakeLists.txt

@@ -44,6 +44,4 @@ set (TESTS
 
 add_executable(program ${SOURCES} ${TESTS})
 
-target_link_libraries(program minhash_lib)
-
-# add_dependencies(program minhash)
+target_link_libraries(program minhash_lib)

README.md

@@ -43,11 +43,11 @@ Second, run CMake with a compiler that you like. On Windows the default compiler
 
 ### Windows 10
 
-```cd build/; cmake ../ . -G "MinGW Makefiles" .; make;```
+```cd build/; cmake ../. -G "MinGW Makefiles" .; make;```
 
 ### MacOS
 
-```cd build/; cmake ../ .; make;```
+```cd build/; cmake ../.; make;```
 
 Finally, run the application using generated target file:
 
@@ -62,4 +62,4 @@ Finally, run the application using generated target file:
 5. Testing
     * scalar operation
     * SIMD operation
-    * count and compare execution times
+    * count and compare execution times

include/application.h

@@ -13,24 +13,39 @@
 #define DEFAULT_ARRAY_SIZE 10000000
 #define DEBUG 0
 
+/**
+ * Application class manages entire project.
+ **/
 class Application
 {
 public:
+    // Constructor which takes argument count and arguments from commands line.
     Application(int, char*[]);
     ~Application();
 
+    // Starts the application.
     void run();
+
+    // Runs default tests for every MinHash implementation.
     void runDefaultTests();
+
+    // Runs series of performance tests for every MinHash implementation
+    // and custom array lengths.
     void runPerformanceTests();
-    TestingResult runSpecificPerformanceTest(TestingCase, int, const std::string &);
 
 private:
-    std::chrono::duration<double> getExecutionTime();
+    // Runs specific performance test with custom conditions.
+    TestingResult runSpecificPerformanceTest(TestingCase, int, const std::string &);
+
+    // Shows summary for a specific testing result.
     void showTestingResultSummary(TestingResult testingResult);
+
+    // Shows summary for all gathered testing results.
     void showAllTestingResultsSummary(std::vector<TestingResult> &);
+
+    // Gets string representation of specific extension.
     std::string getStringFromExtension(Extension extension);
 
-private:
     ArgManager * argManager;
     ExtensionDetector * extensionDetector;
     FileManager * fileManager;

include/argmanager.h

@@ -4,14 +4,29 @@
 #include <string.h>
 #include <fstream>
 
+/**
+ * ArgManager takes care of arguments passed from command line to the application.
+ **/
 class ArgManager
 {
 public:
+    // Constructor which takes argument count and arguments from commands line.
     ArgManager(int, char*[]);
+
+    // Gets name of the input file passed to the application.
     std::string getInputFileName();
+
+    // Gets name of the output file passed to the application.
     std::string getOutputtFileName();
+
+    // Returns true if "-p" flag was passed to the application.
     bool shouldRunPerformanceTests();
+
+    // Returns true if "-test" flag was passed to the application.
     bool shouldRunUnitTests();
+
+    // Returns true if "-help" flag was passed to the application.
+    bool shouldShowHelp();
 
 private:
     int size;

include/arraygenerator.h

@@ -4,14 +4,24 @@
 #include <random>
 #include <ctime>
 
+/**
+ * ArrayGenerator generates uint64_t arrays.
+ **/
 class ArrayGenerator
 {
 public:
+    // Default constructor of ArrayGenerator.
     ArrayGenerator();
+
+    // Generates empty uint64_t array of given length and returns it.
     uint64_t * generateUint64Array(int);
+
+    // Generates uint64_t array of given length and returns it
+    // filled with numbers generated by the random numbers generator 
     uint64_t * generateRandomUint64Array(int);
 
 private:
+    // Generates single random uint64_t number.
     uint64_t generateRandomUint64();
 
     unsigned int seed;

include/arraymanager.h

@@ -8,12 +8,20 @@
 class ArrayManager
 {
 public:
+    // Constructor with an argument as array length.
     ArrayManager(int);
+
+    // Constructor with an argument as another ArrayManager.
     ArrayManager(ArrayManager&);
     ~ArrayManager();
 
+    // Returns input array filled with random uint64_t values.
     uint64_t *& getInputArray();
+
+    // Returns empty output array.
     uint64_t *& getOutputArray();
+
+    // Gets size of the arrays which are always the same.
     unsigned int getSize();
 
 private:

include/extensiondetector.h

@@ -22,7 +22,11 @@ enum Extension
 class ExtensionDetector
 {
 public:
+    // Checks extensions supported by processor.
+    // Returns vector containing list of them.
     std::vector<Extension> checkAvailableExtensions();
+
+    // Runs algorithm performing decision for choosing extension.
     Extension chooseExtension();
 
 private:

include/extensionmanager.h

@@ -3,9 +3,13 @@
 #include "minhash.h"
 #include "extensiondetector.h"
 
+/**
+ * ExtensionManager manages MinHash implementation using extensions.
+ **/
 class ExtensionManager
 {
 public:
+    // Returns new MinHash instance using specific extension as a parameter.
     minhash::MinHash * getMinHashInstance(Extension);
 };
 

include/filemanager.h

@@ -6,18 +6,35 @@
 #include "testingresult.h"
 #include "extension.h"
 
+/**
+ * FileManager manages input and output files.
+ **/
 class FileManager
 {
 public:
+    // Constructor taking as a parameter input and output files names.
     FileManager(const std::string &, const std::string &);
+
+    // Returns vector of testing cases defined in input file.
     std::vector<TestingCase> readDataFromInputFile();
+
+    // Writes data in a form of testing results to the output file.
     bool writeDataToOutputFile(std::vector<TestingResult> &);
+
+    // Write data in a form of vector of execution times.
     bool writeDataToOutputFile(std::vector<std::chrono::duration<double>> &);
 
 private:
+    // Splits string into tokens using specific delimiter.
     std::vector<std::string> split(const std::string& s, char delimiter);
+
+    // Gets extension type using its string representation.
     Extension getExtension(const std::string &);
+
+    // Gets size array defined as a string from an input file.
     int getSize(const std::string &);
+
+    // Checks if a string is a number.
     bool isNumber(const std::string &);
 
 private:

include/osdetector.h

@@ -12,12 +12,13 @@ enum OSType
 	UNKNOWN
 };
 
-/*
- OSDetector checks operating system that application runs on.
-*/
+/**
+ * OSDetector checks operating system that application runs on.
+ **/
 class OSDetector
 {
 public:
+	// Returns type of the operating system that application runs on.
 	OSType checkOS();
 };
 

include/testingcase.h

@@ -4,11 +4,20 @@
 #include <vector>
 #include <extensiondetector.h>
 
+/**
+ * TestingCase is a combination of extention type and array length which
+ * represents a single test to run in the application.
+ **/
 class TestingCase
 {
 public:
+    // Constructor that takes extension type and array length as parameters.
     TestingCase(Extension, unsigned int);
+
+    // Gets extension type defined in testing case.
     Extension getExtension();
+
+    // Gets array length defined in testing case.
     unsigned int getArraySize();
 
 private:

include/testingmanager.h

@@ -6,15 +6,24 @@
 #include "extensionmanager.h"
 #include "minhash.h"
 
+/**
+ * TestingManager performs tests in application.
+ **/
 class TestingManager
 {
 public:
+    // Default constructor of the application.
     TestingManager();
     ~TestingManager();
+
+    // Runs all tests defined in passed vector of testing cases. 
     void runAllTests(std::vector<TestingCase>&);
+
+    // Returns vector containg results of defined testing cases.
     std::vector<TestingResult> & getTestingResults();
 
 private:
+    // Run single testing case and returns its results.
     TestingResult runSingleTest(TestingCase);
 
 private:

include/testingresult.h

@@ -3,11 +3,19 @@
 #include "testingcase.h"
 #include <chrono>   
 
+/**
+ * TestingResult contains information about performed testing case and its results.
+ **/
 class TestingResult
 {
 public:
+    // Constructor taking as parameters testing case and its execution time.
     TestingResult(TestingCase, std::chrono::duration<double>);
+
+    // Returns testing case defined for testing result.
     TestingCase getTestingCase();
+
+    // Returns execution time of the performed testing case.
     std::chrono::duration<double> getExecutionTime();
 
 private:

minhash/avx2.h

@@ -8,12 +8,16 @@
 
 namespace minhash
 {
+    /**
+     * AVX2 provides MinHash implementation for AVX2 SIMD extension.
+     **/
     class AVX2 : public minhash::MinHasher
     {
     public:
         AVX2();
         virtual ~AVX2();
 
+        // Iterates through arrays to count MinHash for every element.
         virtual inline void minHash(uint64_t*& input, uint64_t*& output, int size) override
         {
             for (unsigned int i = 0; i < size; i += this->getElementsInOneCall())
@@ -23,6 +27,7 @@ namespace minhash
         }
 
     private:
+        // Performs counting MinHash using AVX2 extension data types and instructions.
         void inline countPack(uint64_t*& input, uint64_t*& output, int offset)
         {
             __m256i h, h1, h2, h3;
@@ -64,6 +69,7 @@ namespace minhash
             _mm256_store_si256((__m256i*)&output[offset], h3);            
         }
 
+        // Rotates argument using shift and XOR operations.
         __m256i inline fmix64(__m256i x)
         {
             __m256i t1;
@@ -93,23 +99,26 @@ namespace minhash
             return x;
         }
 
+        // Rotates argument using shift and OR operations.
         __m256i inline rotl64(__m256i x, int32_t offset)
         {
             return _mm256_or_si256( _mm256_slli_epi64(x, offset), _mm256_srli_epi64(x, 64 - offset));
         }
 
+        // Multiplies two 256-bit values.
         __m256i inline multiply64Bit(__m256i a, __m256i b)
         {
-            __m256i bswap   = _mm256_shuffle_epi32(b,0xB1);           // swap H<->L
-            __m256i prodlh  = _mm256_mullo_epi32(a,bswap);            // 32 bit L*H products
-            __m256i zero    = _mm256_setzero_si256();                 // 0
-            __m256i prodlh2 = _mm256_hadd_epi32(prodlh,zero);         // a0Lb0H+a0Hb0L,a1Lb1H+a1Hb1L,0,0
+            __m256i bswap   = _mm256_shuffle_epi32(b,0xB1);           // Swaps H with L register.
+            __m256i prodlh  = _mm256_mullo_epi32(a,bswap);            // 32 bit L*H products.
+            __m256i zero    = _mm256_setzero_si256();                 // Zeroing register.
+            __m256i prodlh2 = _mm256_hadd_epi32(prodlh,zero);         // a0Lb0H + a0Hb0L, a1Lb1H + a1Hb1L, 0, 0
             __m256i prodlh3 = _mm256_shuffle_epi32(prodlh2,0x73);     // 0, a0Lb0H+a0Hb0L, 0, a1Lb1H+a1Hb1L
-            __m256i prodll  = _mm256_mul_epu32(a,b);                  // a0Lb0L,a1Lb1L, 64 bit unsigned products
-            __m256i prod    = _mm256_add_epi64(prodll,prodlh3);       // a0Lb0L+(a0Lb0H+a0Hb0L)<<32, a1Lb1L+(a1Lb1H+a1Hb1L)<<32
+            __m256i prodll  = _mm256_mul_epu32(a,b);                  // a0Lb0L, a1Lb1L, 64 bit unsigned products.
+            __m256i prod    = _mm256_add_epi64(prodll,prodlh3);       // a0Lb0L + (a0Lb0H+a0Hb0L)<<32, a1Lb1L + (a1Lb1H+a1Hb1L)<<32
             return  prod;
         }
 
+        // Prints 256-bit value.
         void printValue(__m256i var);
 
     };

minhash/extension.h

@@ -4,10 +4,14 @@
 
 namespace minhash
 {
+    /**
+     * Extension defines the amount of counts that can be count in a single
+     * iteration using specific extension.
+     **/
     class Extension
     {
     public:
-        virtual ~Extension() {}
+        virtual ~Extension() {};
 
         void setElementsInSingleVariable(const int);
         int getElementsInSingleVariable();

minhash/minhash.h

@@ -5,10 +5,19 @@
 
 namespace minhash
 {
+    /**
+     * MinHash class is a representation of the unit counting MinHash values.
+     **/
     class MinHash
     {
     public:
+        // Constructor that takes MinHasher interface as parameter.
         MinHash(MinHasher*);
+
+        // Method used for counting MinHash values. Parameters are: pointer to the
+        // input array (containing values), pointer to the output values (where
+        // resulting values should be stored) and size of both arrays (that has
+        // to be the same).
         void count(uint64_t*, uint64_t*, int);
 
     private: