fix(doc): Improve codebase into Doxygen-friendly

Some files and parameters are missing from doxygen-generated documentation. The version name in Dockerfile is bumped. Some documents under tangle-accelerator didn't meet the standard of Markdown. However, fenced code block for bash commands, we are always starting with a `$` which doesn't meet the standard of Markdown.
DLTcollab · Jul 1, 2020 · 8cf83e9 · 8cf83e9
1 parent f4e18be
commit 8cf83e9
Show file tree

Hide file tree

Showing 52 changed files with 583 additions and 391 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,22 +1,21 @@
 # Contributing to Tangle-accelerator
 
 When contributing to this repository, please first discuss the change you wish to make via issue,
-email, or any other method with the owners of this repository before making a change. 
+email, or any other method with the owners of this repository before making a change.
 
 Please note we have a code of conduct, please follow it in all your interactions with the project.
 
 ## Pull Request Process
 
-1. Ensure any install or build dependencies are removed before the end of the layer when doing a 
-   build.
+1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
 2. Create a new branch for fixing or developing the changes.
 3. Run test with `bazel test //tests/...`, after finishing the changes.
-4. Update the README.md with details of changes to the interface, which includes new environment 
-   variables, exposed ports, useful file locations and container parameters.
+4. Update the README.md with details of changes to the interface, which includes new environment variables, exposed ports, useful file locations and container parameters.
 5. Run `hooks/formatter` before committing the changes.
 6. Rebase to the latest `develop` branch.
 
 ## Git Commit Message Guidelines
+
 Read this [blog article](https://chris.beams.io/posts/git-commit/) and [this article](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) and follow the instructions in these articles.
 The subject line of git commit message should follow this pattern
 `<type>[optional scope]: <description>`
@@ -28,6 +27,21 @@ The `type` includes the following 5 words depending on the content of the commit
 * test
 * doc
 
+## Doxygen-friendly Representation
+
+Function parameters should be in the following style or [doxygen official example](https://www.doxygen.nl/manual/commands.html#cmdparam) which allows the generating doxygen documentation.
+
+```c
+/**
+ * Copies bytes from a source memory area to a destination memory area,
+ * where both areas may not overlap.
+ * @param[out] dest The memory area to copy to.
+ * @param[in]  src  The memory area to copy from.
+ * @param[in]  n    The number of bytes to copy
+ */
+void memcpy(void *dest, const void *src, size_t n);
+```
+
 ## Code of Conduct
 
 ### Our Pledge

diff --git a/Doxyfile b/Doxyfile
@@ -1,6 +1,6 @@
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "tangle-accelerator"
-PROJECT_NUMBER         = 0.1.0
+PROJECT_NUMBER         = 0.9.2
 OUTPUT_DIRECTORY       = docs/
 OPTIMIZE_OUTPUT_FOR_C  = YES
 INPUT                  = . \
@@ -9,13 +9,19 @@ INPUT                  = . \
                         accelerator/core/request \
                         accelerator/core/response \
                         accelerator/core/serializer \
+                        endpoint \
+                        endpoint/endpointComp \
+                        endpoint/hal \
+                        endpoint \
                         utils \ 
+                        utils/cache \ 
                         common \
                         storage \
                         connectivity/mqtt \
                         connectivity/http
 FILE_PATTERNS          = *.h \
-                        *.md
+                        *.md \
+                        *.c
 EXAMPLE_PATH           = tests
 EXAMPLE_PATTERNS       = test_*
 USE_MDFILE_AS_MAINPAGE = README.md

diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ both footprint and startup time are behaved pretty well.
 
 ```
                 +-------------------------------------------+
-+----------+    |  +-----------------+       +-----------+  |       
++----------+    |  +-----------------+       +-----------+  |
 |          |    |  | Service         |       | Cache     |  |
 |  Client  <-----> |                 | <---> |           |  |
 |          |    |  | -Explorer       |       | -Trytes   |  |
@@ -37,7 +37,7 @@ both footprint and startup time are behaved pretty well.
                 |  | -Proxy          |       |           |  |
                 |  +-----------------+       +-----------+  |
                 |         ^                                 |
-                +---------|---------------------------------+     
+                +---------|---------------------------------+
                           v
                 +-------------------------------------------+  
                 | Full Node                                 |
@@ -52,7 +52,7 @@ both footprint and startup time are behaved pretty well.
 
 `Tangle-accelerator` helps to reattach pending transactions were attached from `Tangle-accelerator`.
 Reattachment increases chances of confirmation and prevents messages being pruned when full nodes perform snapshot.
-Clients should provide a unique ID as the identifier to each message and it's corresponding transaction hash since a new transaction hash will be generated after reattachment. 
+Clients should provide a unique ID as the identifier to each message and it's corresponding transaction hash since a new transaction hash will be generated after reattachment.
 
 `Tangle-accelerator` uses ScyllaDB to store each transaction's ID, hash and status(Pending or confirmed). `Tangle-accelerator` will periodically check the status of pending transactions and reattach transactions which have been pended too long. Confirmed transactions will be stored into permanodes.
 
@@ -61,20 +61,23 @@ Clients can find the transaction alone with wanted message by using the ID to qu
 ## Connectivity
 
 `Tangle-accelerator`, at this moment, supports the following TCP/IP derived protocols:
+
 * `HTTP`
-* `MQTT` 
+* `MQTT`
 
 ### HTTP
+
 `HTTP` can be used in the normal internet service. User can use RESTful APIs to interact with `tangle-accelerator`.
 
 ### MQTT
+
 `MQTT` is a lightweight communication protocol which can be used in the IoT scenarios. `Tangle-accelerator`'s support to `MQTT` allows embedded devices to write data on IOTA internet with relative low quality hardware devices. We hope this will speed up DLT into our daily life.
 
 ## Documentation
 
 This page contains basic instructions for setting up tangle-accelerator, You can generate full documentation and API reference via Doxygen. The documentation is under `docs/` after generated:
 
-```
+```bash
 $ doxygen Doxyfile
 ```
 
@@ -99,7 +102,7 @@ Before running tangle-accelerator, please edit binding address/port of accelerat
 * `http_threads`: Determine thread pool size to process HTTP connections.
 * `quiet`: Turn off logging message.
 
-```
+```bash
 $ make && bazel run //accelerator
 ```
 
@@ -114,66 +117,79 @@ Tangle-accelerator supports several different build time options.
 
 Debug mode enables tangle-accelerator to display extra `debug` logs.
 
+```bash
+$ bazel run --define build_type=debug //accelerator
 ```
-bazel run --define build_type=debug //accelerator
-```
+
 * Profiling Mode
 
-    Profiling mode adds `-pg` flag when compiling tangle-accelerator. This allows tangle-accelerator to write profile information for the analysis program gprof.
-```
-bazel run --define build_type=profile //accelerator
+Profiling mode adds `-pg` flag when compiling tangle-accelerator. This allows tangle-accelerator to write profile information for the analysis program gprof.
+
+```bash
+$ bazel run --define build_type=profile //accelerator
 ```
 
 See [docs/build.md](docs/build.md) for more information.
 
 ## Developing
 
 The codebase of this repository follows [Google's C++ guidelines](https://google.github.io/styleguide/cppguide.html):
-- Please run `hooks/autohook.sh install` after initial checkout.
-- Pass `-c dbg` for building with debug symbols.
+
+* Please run `hooks/autohook.sh install` after initial checkout.
+* Pass `-c dbg` for building with debug symbols.
 
 ### Tools required for running git commit hook
-- buildifier
-- clang-format
+
+* buildifier
+* clang-format
 
 ### Buildifier
+
 Buildifier can be installed with `bazel` or `go`
 
 #### Install with go
+
 1. change directory to `$GOPATH`
 2. run `$ go get github.com/bazelbuild/buildtools/buildifier`
    The executable file will be located under `$GOPATH/bin`
 3. make a soft link for global usage, run
    `$ sudo ln -s $HOME/go/bin/buildifier /usr/bin/buildifier`
 
 #### Install with bazel
+
 1. clone `bazelbuild/buildtools` repository
    `$ git clone https://github.com/bazelbuild/buildtools.git`
 2. change directory to `buildtools`
 3. build it with bazel command, `$ bazel build //buildifier`
    The executable file will be located under `path/to/buildtools/bazel-bin`
-4. make a soft link or move the executable file under `/usr/bin` 
+4. make a soft link or move the executable file under `/usr/bin`
 
 ### clang-format
+
 clang-format can be installed by command:
-- Debian/Ubuntu based systems: `$ sudo apt-get install clang-format`
-- macOS: `$ brew install clang-format`
 
+* Debian/Ubuntu based systems: `$ sudo apt-get install clang-format`
+* macOS: `$ brew install clang-format`
 
 ## Usage
+
 `Tangle-accelerator` currently supports two categories of APIs
+
 * Direct API: check [wiki page](https://github.com/DLTcollab/tangle-accelerator/wiki) for details.
 * Proxy API to IOTA core functionalities
 
 ### Full Node Proxy API
+
 `tangle-accelerator` allows the use of IOTA core APIs. The calling process does not have to be aware of the destination machine running IOTA full node. With the exactly same format of IOTA core APIs, `tangle-accelerator` would help users forward the request to IOTA full node and forward the response back to users.
 We support two way to forward Proxy APIs to IOTA full node:
+
 1. Bypass Proxy APIs directly to IOTA full node.
 2. Process the Proxy APIs, then transmit them to IOTA full node.
 
 The user can choose which way they want with CLI argument `--proxy_passthrough`.
 All the Proxy APIs are supported with the first way.
 However, the second way currently only supports the followings Proxy APIs:
+
 * checkConsistency
 * findTransactions
 * getBalances
@@ -182,5 +198,6 @@ However, the second way currently only supports the followings Proxy APIs:
 * getTrytes
 
 ## Licensing
+
 `Tangle-accelerator` is freely redistributable under the MIT License. Use of this source
 code is governed by a MIT-style license that can be found in the `LICENSE` file.