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 · 9182338 · 9182338
1 parent ea1dfdf
commit 9182338
Show file tree

Hide file tree

Showing 6 changed files with 87 additions and 10 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,38 @@
+#---------------------------------------------------------------------------
+# 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
+EXAMPLE_PATH           = tests
+EXAMPLE_PATTERNS       = test-*.c
+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
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+MACRO_EXPANSION        = YES
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,13 +23,17 @@
 #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
 
+/**
+ * @file dcurl.c
+ */
+
 /* check whether dcurl is initialized */
 static bool isInitialized = false;
 
@@ -58,6 +61,15 @@ extern ImplContext PoWCL_Context;
 extern ImplContext PoWFPGAAccel_Context;
 #endif
 
+/**
+ * @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()
 {
     bool ret = true;
@@ -86,6 +98,12 @@ bool dcurl_init()
     return isInitialized = ret;
 }
 
+/**
+ * @brief dcurl destruction.
+ *
+ * Remove the registered hardware from the list and release the corresponding
+ * resource.
+ */
 void dcurl_destroy()
 {
     ImplContext *impl = NULL;
@@ -99,6 +117,17 @@ 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 The thread number of calculating the PoW. It affects CPU
+ * only.
+ * @return The result of PoW.
+ */
 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,6 +4,10 @@
 #include <stdbool.h>
 #include "trinary.h"
 
+/**
+ * @file dcurl.h
+ */
+
 bool dcurl_init();
 void dcurl_destroy();
 int8_t *dcurl_entry(int8_t *trytes, int mwm, int threads);