From 0092cabbb79d72cf5c350e4e2d1faf2a4bbdcd5b Mon Sep 17 00:00:00 2001
From: Artur Khudiaev <artur.khudiaev@demlabs.net>
Date: Mon, 25 Oct 2021 12:52:32 +0000
Subject: [PATCH] Docs sdk

---
 dap-sdk/crypto/include/dap_hash.h             | 16 ++++--
 modules/chain/dap_chain.c                     | 19 ++++---
 modules/chain/dap_chain_cs.c                  |  4 +-
 modules/chain/dap_chain_ledger.c              | 12 +++--
 modules/chain/dap_chain_vf.c                  | 13 +++--
 .../consensus/dag-poa/dap_chain_cs_dag_poa.c  | 53 +++++++++++--------
 modules/net/dap_chain_net.c                   | 15 ++++--
 7 files changed, 88 insertions(+), 44 deletions(-)

diff --git a/dap-sdk/crypto/include/dap_hash.h b/dap-sdk/crypto/include/dap_hash.h
index e28f98ec4b..a0d586fc9e 100755
--- a/dap-sdk/crypto/include/dap_hash.h
+++ b/dap-sdk/crypto/include/dap_hash.h
@@ -56,6 +56,15 @@ extern "C" {
 //size_t dap_chain_hash_fast_to_str(dap_chain_hash_fast_t * a_hash, char * a_str, size_t a_str_max);
 int dap_chain_hash_fast_from_str( const char * a_hash_str, dap_hash_fast_t * a_hash);
 
+/**
+ * @brief 
+ * get SHA3_256 hash for specific data
+ * @param a_data_in input data
+ * @param a_data_in_size size of input data
+ * @param a_hash_out returned hash
+ * @return true 
+ * @return false 
+ */
 static inline bool dap_hash_fast( const void *a_data_in, size_t a_data_in_size, dap_hash_fast_t *a_hash_out )
 {
     if ( (a_data_in == NULL) || (a_data_in_size == 0) || (a_hash_out == NULL) )
@@ -72,9 +81,10 @@ static inline bool dap_hash_fast( const void *a_data_in, size_t a_data_in_size,
 
 
 /**
- * @brief dap_hash_fast_compare
- * @param a_hash1
- * @param a_hash2
+ * @brief 
+ * compare to hashes (dap_hash_fast_t) through memcmp
+ * @param a_hash1 - dap_hash_fast_t hash1
+ * @param a_hash2 - dap_hash_fast_t hash2
  * @return
  */
 static inline bool dap_hash_fast_compare(dap_hash_fast_t *a_hash1, dap_hash_fast_t *a_hash2)
diff --git a/modules/chain/dap_chain.c b/modules/chain/dap_chain.c
index 7b1413854c..514de1819e 100644
--- a/modules/chain/dap_chain.c
+++ b/modules/chain/dap_chain.c
@@ -129,12 +129,14 @@ void dap_chain_enum_unlock(void)
 }
 
 /**
- * @brief dap_chain_create
- * @param a_chain_net_name
- * @param a_chain_name
- * @param a_chain_net_id
- * @param a_chain_id
- * @return
+ * @brief 
+ * create dap chain object
+ * @param a_ledger dap_ledger_t ledger object
+ * @param a_chain_net_name blockchain network name
+ * @param a_chain_name chain name
+ * @param a_chain_net_id 
+ * @param a_chain_id chain id
+ * @return dap_chain_t* 
  */
 dap_chain_t * dap_chain_create(dap_ledger_t* a_ledger, const char * a_chain_net_name, const char * a_chain_name, dap_chain_net_id_t a_chain_net_id, dap_chain_id_t a_chain_id )
 {
@@ -159,8 +161,9 @@ dap_chain_t * dap_chain_create(dap_ledger_t* a_ledger, const char * a_chain_net_
 }
 
 /**
- * @brief dap_chain_delete
- * @param a_chain
+ * @brief
+ * delete dap chain object
+ * @param a_chain dap_chain_t object
  */
 void dap_chain_delete(dap_chain_t * a_chain)
 {
diff --git a/modules/chain/dap_chain_cs.c b/modules/chain/dap_chain_cs.c
index fefcca077c..6aff47a9d6 100644
--- a/modules/chain/dap_chain_cs.c
+++ b/modules/chain/dap_chain_cs.c
@@ -114,8 +114,8 @@ void dap_chain_cs_add (const char * a_cs_str,  dap_chain_callback_new_cfg_t a_ca
  * get consensus from chain cfg file [dag_pos, dag_poa, block_poa, none]
  * dap_config_get_item_str( a_chain_cfg, "chain", "consensus");
  * verify if consensus was created by dap_chain_cs_add function
- * @param a_chain
- * @param a_chain_cfg
+ * @param a_chain dap_chain_t chain object
+ * @param a_chain_cfg dap_config_t 
  * @return
  */
 int dap_chain_cs_create(dap_chain_t * a_chain, dap_config_t * a_chain_cfg)
diff --git a/modules/chain/dap_chain_ledger.c b/modules/chain/dap_chain_ledger.c
index c31a4edfd4..a7db5c8562 100644
--- a/modules/chain/dap_chain_ledger.c
+++ b/modules/chain/dap_chain_ledger.c
@@ -1045,9 +1045,15 @@ void dap_chain_ledger_load_cache(dap_ledger_t *a_ledger)
 }
 
 /**
- * @brief dap_chain_ledger_create
- * @param a_check_flags
- * @return dap_ledger_t
+ * @brief 
+ * create ledger for specific net
+ * load ledger cache
+ * @param a_check_flags checking flags
+ *          DAP_CHAIN_LEDGER_CHECK_TOKEN_EMISSION
+ *          DAP_CHAIN_LEDGER_CHECK_CELLS_DS
+ *          DAP_CHAIN_LEDGER_CHECK_CELLS_DS
+ * @param a_net_name char * network name, for example "kelvin-testnet"
+ * @return dap_ledger_t* 
  */
 dap_ledger_t* dap_chain_ledger_create(uint16_t a_check_flags, char *a_net_name)
 {
diff --git a/modules/chain/dap_chain_vf.c b/modules/chain/dap_chain_vf.c
index c35a2366e8..d6797bea07 100644
--- a/modules/chain/dap_chain_vf.c
+++ b/modules/chain/dap_chain_vf.c
@@ -28,7 +28,9 @@
 #define LOG_TAG "dap_chain_vf"
 
 /**
- * @brief dap_chain_vf_init
+ * @brief
+ * empty function
+ * return 0
  * @return
  */
 int dap_chain_vf_init()
@@ -37,7 +39,8 @@ int dap_chain_vf_init()
 }
 
 /**
- * @brief dap_chain_vf_deinit
+ * @brief
+ * empty function
  */
 void dap_chain_vf_deinit()
 {
@@ -45,7 +48,9 @@ void dap_chain_vf_deinit()
 }
 
 /**
- * @brief dap_chain_vf_add
+ * @brief 
+ * empty function
+ * return 0
  * @param a_vf_id
  * @param a_callback
  * @return
@@ -57,6 +62,8 @@ int dap_chain_vf_add(dap_chain_vf_id_t a_vf_id, dap_chain_vf_callback_t a_callba
 
 /**
  * @brief dap_chain_vf_check
+ * empty function
+ * return true
  * @param a_vf_id
  * @param a_ledger
  * @param a_receipt
diff --git a/modules/consensus/dag-poa/dap_chain_cs_dag_poa.c b/modules/consensus/dag-poa/dap_chain_cs_dag_poa.c
index cd5e776794..687e0dccdc 100644
--- a/modules/consensus/dag-poa/dap_chain_cs_dag_poa.c
+++ b/modules/consensus/dag-poa/dap_chain_cs_dag_poa.c
@@ -73,8 +73,11 @@ static dap_chain_cs_dag_event_t * s_callback_event_create(dap_chain_cs_dag_t * a
 static int s_cli_dag_poa(int argc, char ** argv, void *arg_func, char **str_reply);
 
 static bool s_seed_mode = false;
+
 /**
- * @brief dap_chain_cs_dag_poa_init
+ * @brief
+ * init consensus dag_poa
+ * read parameters from config and register dag_poa commands to cellframe-node-cli
  * @return
  */
 int dap_chain_cs_dag_poa_init(void)
@@ -100,9 +103,10 @@ void dap_chain_cs_dag_poa_deinit(void)
 
 
 /**
- * @brief s_cli_dag_poa
- * @param argc
- * @param argv
+ * @brief
+ * parse and execute cellframe-node-cli dag-poa commands
+ * @param argc arguments count
+ * @param argv array with arguments
  * @param arg_func
  * @param str_reply
  * @return
@@ -219,8 +223,11 @@ static int s_cli_dag_poa(int argc, char ** argv, void *arg_func, char **a_str_re
 
 /**
  * @brief s_cs_callback
- * @param a_chain
- * @param a_chain_cfg
+ * dap_chain_callback_new_cfg_item_t->callback_init function.
+ * get dag-poa consensus parameters from config
+ * and set dap_chain_cs_dag_t l_dag->chain->callback_created = s_callback_new
+ * @param a_chain dap_chain_t chain object
+ * @param a_chain_cfg chain config object
  */
 static int s_callback_new(dap_chain_t * a_chain, dap_config_t * a_chain_cfg)
 {
@@ -262,8 +269,8 @@ static int s_callback_new(dap_chain_t * a_chain, dap_config_t * a_chain_cfg)
 /**
  * @brief create callback load certificate for event signing for specific chain
  * path to certificate iw written to chain config file in dag_poa section
- * @param a_chain chain object
- * @param a_chain_net_cfg 
+ * @param a_chain chain object (for example, a_chain.name = zerochain, a_chain.network = kelvin-testnet)
+ * @param a_chain_net_cfg dap_config_t network config object
  * @return
  */
 static int s_callback_created(dap_chain_t * a_chain, dap_config_t *a_chain_net_cfg)
@@ -288,8 +295,9 @@ static int s_callback_created(dap_chain_t * a_chain, dap_config_t *a_chain_net_c
 }
 
 /**
- * @brief s_chain_cs_dag_callback_delete
- * @param a_dag
+ * @brief 
+ * delete dap_chain_cs_dag_poa_pvt_t callback
+ * @param a_dag dap_chain_cs_dag_t object
  */
 static void s_callback_delete(dap_chain_cs_dag_t * a_dag)
 {
@@ -313,12 +321,14 @@ static void s_callback_delete(dap_chain_cs_dag_t * a_dag)
 }
 
 /**
- * @brief s_callback_event_create
- * @param a_dag
- * @param a_datum
- * @param a_hashes
- * @param a_hashes_count
- * @return
+ * @brief 
+ * callback for create event operation
+ * @param a_dag dap_chain_cs_dag_t DAG object
+ * @param a_datum dap_chain_datum_t
+ * @param a_hashes  dap_chain_hash_fast_t 
+ * @param a_hashes_count size_t
+ * @param a_dag_event_size size_t
+ * @return dap_chain_cs_dag_event_t* 
  */
 static dap_chain_cs_dag_event_t * s_callback_event_create(dap_chain_cs_dag_t * a_dag, dap_chain_datum_t * a_datum,
                                                           dap_chain_hash_fast_t * a_hashes, size_t a_hashes_count, size_t* a_event_size)
@@ -339,12 +349,13 @@ static dap_chain_cs_dag_event_t * s_callback_event_create(dap_chain_cs_dag_t * a
 }
 
 
-
 /**
- * @brief s_chain_cs_dag_callback_event_verify
- * @param a_dag
- * @param a_dag_event
- * @return
+ * @brief 
+ * function makes event singing verification
+ * @param a_dag dag object
+ * @param a_dag_event dap_chain_cs_dag_event_t
+ * @param a_dag_event_size size_t size of event object
+ * @return int 
  */
 static int s_callback_event_verify(dap_chain_cs_dag_t * a_dag, dap_chain_cs_dag_event_t * a_dag_event, size_t a_dag_event_size)
 {
diff --git a/modules/net/dap_chain_net.c b/modules/net/dap_chain_net.c
index 740e10fca0..9c4543979b 100644
--- a/modules/net/dap_chain_net.c
+++ b/modules/net/dap_chain_net.c
@@ -1061,7 +1061,9 @@ void dap_chain_net_delete( dap_chain_net_t * a_net )
 
 
 /**
- * @brief dap_chain_net_init
+ * @brief
+ * init network settings from cellrame-node.cfg file
+ * register net* commands in cellframe-node-cli interface
  * @return
  */
 int dap_chain_net_init()
@@ -1105,6 +1107,10 @@ int dap_chain_net_init()
     return 0;
 }
 
+/**
+ * @brief 
+ * load network config settings
+ */
 void dap_chain_net_load_all()
 {
     char * l_net_dir_str = dap_strdup_printf("%s/network", dap_config_path());
@@ -1173,9 +1179,10 @@ void s_set_reply_text_node_status(char **a_str_reply, dap_chain_net_t * a_net){
 }
 
 /**
- * @brief s_cli_net
- * @param argc
- * @param argv
+ * @brief
+ * register net* command in cellframe-node-cli interface
+ * @param argc arguments count
+ * @param argv arguments value
  * @param arg_func
  * @param str_reply
  * @return
-- 
GitLab