Merge pull request #115 from marktwtn/semantic-versioning

Improve Doxgen-friendly comments

.gitignore

@@ -1,5 +1,6 @@
 # Generated files
 build/
+docs/html
 
 # Object files                                                                                                                                                
 *.o

Doxyfile

@@ -0,0 +1,32 @@
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+PROJECT_NAME           = "dcurl"
+PROJECT_NUMBER         = 0.1.0
+OUTPUT_DIRECTORY       = docs
+OPTIMIZE_OUTPUT_FOR_C  = YES
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = . \
+                         docs \
+                         src
+FILE_PATTERNS          = dcurl.c \
+                         dcurl.h \
+                         *.md
+USE_MDFILE_AS_MAINPAGE = README.md
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO

README.md

@@ -2,6 +2,7 @@
 
 [![Build Status](https://travis-ci.org/DLTcollab/dcurl.svg?branch=dev)](https://travis-ci.org/DLTcollab/dcurl)
 ![Supported IRI version](https://img.shields.io/badge/Supported%20IRI%20Version-1.6.0-brightgreen.svg)
+![Release version](https://img.shields.io/github/release-pre/DLTcollab/dcurl.svg)
 
 Hardware-accelerated implementation for IOTA PearlDiver, which utilizes multi-threaded SIMD, FPGA and GPU.
 

src/common.h

@@ -4,6 +4,10 @@
 #include <stdint.h>
 #include <time.h>
 
+#define __DCURL_MAJOR__ 0
+#define __DCURL_MINOR__ 1
+#define __DCURL_PATCH__ 0
+
 double diff_in_second(struct timespec t1, struct timespec t2);
 
 typedef struct _pow_info PoW_Info;

src/dcurl.h

@@ -4,8 +4,51 @@
 #include <stdbool.h>
 #include "trinary.h"
 
+/**
+ * @file dcurl.h
+ * @brief dcurl API functions.
+ *
+ * dcurl is a hardware-accelerated implementation for IOTA PearlDiver.
+ * It supports multi-threaded SIMD on CPU, OpenCL on GPU and FPGA to
+ * make a faster proof-of-work(PoW) for IOTA.
+ * The API functions can be used to initialize, execute and destroy dcurl
+ * easily.
+ */
+
+/**
+ * @brief dcurl initialization.
+ *
+ * Register the determined hardware into the list and initialize the
+ * corresponding resource.
+ * @return
+ * - true: initialization succeeded.
+ * - false: initialization failed.
+ */
 bool dcurl_init();
+
+/**
+ * @brief dcurl destruction.
+ *
+ * Remove the registered hardware from the list and release the corresponding
+ * resource.
+ */
 void dcurl_destroy();
+
+/**
+ * @brief dcurl execution.
+ *
+ * Retrieve the available hardware from the list and use it to do the
+ * PoW(Proof-of-Work).
+ * @param [in] trytes The trytes for PoW calculation.
+ * @param [in] mwm The minimum weight magnitude.
+ * @param [in] threads
+ * @parblock
+ * The thread number of calculating the PoW. It affects CPU only.
+ *
+ * 0: use (maximum threads - 1).
+ * @endparblock
+ * @return The result of PoW.
+ */
 int8_t *dcurl_entry(int8_t *trytes, int mwm, int threads);
 
 #endif