docs: add the comment and version of dcurl API

Add the comment and configuration file of Doxygen to generate the API document. The README.md also adds a badge of the github release version. At last, the new macros for dcurl version are added.
DLTcollab · Feb 26, 2019 · 6eeb3ae · 6eeb3ae
1 parent ea1dfdf
commit 6eeb3ae
Show file tree

Hide file tree

Showing 6 changed files with 83 additions and 11 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 # Generated files
 build/
+docs/html
 
 # Object files                                                                                                                                                
 *.o

diff --git a/Doxyfile b/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
diff --git a/README.md b/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.
 

diff --git a/src/common.h b/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;

diff --git a/src/dcurl.c b/src/dcurl.c
@@ -9,11 +9,10 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <unistd.h>
-#if defined(ENABLE_OPENCL)
-#include "pow_cl.h"
-#endif
-#if defined(ENABLE_FPGA_ACCEL)
-#include "pow_fpga_accel.h"
+#ifdef __APPLE__
+#include <dispatch/dispatch.h>
+#else
+#include <semaphore.h>
 #endif
 #include "implcontext.h"
 #include "trinary.h"
@@ -24,11 +23,11 @@
 #elif defined(ENABLE_GENERIC)
 #include "pow_c.h"
 #endif
-
-#ifdef __APPLE__
-#include <dispatch/dispatch.h>
-#else
-#include <semaphore.h>
+#if defined(ENABLE_OPENCL)
+#include "pow_cl.h"
+#endif
+#if defined(ENABLE_FPGA_ACCEL)
+#include "pow_fpga_accel.h"
 #endif
 
 /* check whether dcurl is initialized */
@@ -98,7 +97,6 @@ void dcurl_destroy()
     }
 }
 
-
 int8_t *dcurl_entry(int8_t *trytes, int mwm, int threads)
 {
     void *pow_ctx = NULL;

diff --git a/src/dcurl.h b/src/dcurl.h
@@ -4,8 +4,44 @@
 #include <stdbool.h>
 #include "trinary.h"
 
+/**
+ * @file dcurl.h
+ */
+
+/**
+ * @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