From 04f7241a9211678adaabf5de4cfc72bb8fe4155c Mon Sep 17 00:00:00 2001
From: Artur Khudiaev <artur.khudiaev@demlabs.net>
Date: Mon, 25 Oct 2021 11:16:03 +0000
Subject: [PATCH] Docs-sdk

---
 modules/chain/dap_chain.c                     | 28 ++++++++--
 modules/chain/dap_chain_cell.c                | 53 ++++++++++++++-----
 modules/chain/dap_chain_cs.c                  |  8 ++-
 modules/chain/dap_chain_ledger.c              | 17 ++++--
 modules/channel/chain/dap_stream_ch_chain.c   |  6 +--
 .../consensus/dag-poa/dap_chain_cs_dag_poa.c  |  7 +--
 .../consensus/dag-pos/dap_chain_cs_dag_pos.c  | 24 +++++----
 modules/consensus/none/dap_chain_cs_none.c    |  1 +
 modules/net/dap_chain_net.c                   | 25 +++++----
 modules/net/dap_chain_node.c                  |  6 +++
 modules/net/dap_chain_node_cli_cmd.c          |  1 +
 11 files changed, 129 insertions(+), 47 deletions(-)

diff --git a/modules/chain/dap_chain.c b/modules/chain/dap_chain.c
index c0d8c61a17..d38bb251a7 100644
--- a/modules/chain/dap_chain.c
+++ b/modules/chain/dap_chain.c
@@ -234,6 +234,12 @@ dap_chain_t * dap_chain_find_by_id(dap_chain_net_id_t a_chain_net_id,dap_chain_i
     return l_ret_item ? l_ret_item->chain : NULL;
 }
 
+/**
+ * @brief s_chain_type_from_str
+ * get dap_chain_type_t value by str value a_type_str
+ * @param a_type_str str values:token,emission,transaction,ca
+ * @return dap_chain_type_t 
+ */
 static dap_chain_type_t s_chain_type_from_str(const char *a_type_str)
 {
     if(!dap_strcmp(a_type_str, "token")) {
@@ -251,6 +257,12 @@ static dap_chain_type_t s_chain_type_from_str(const char *a_type_str)
     return CHAIN_TYPE_LAST;
 }
 
+/**
+ * @brief s_datum_type_from_str
+ * get datum type (DAP_CHAIN_DATUM_TOKEN_DECL, DAP_CHAIN_DATUM_TOKEN_EMISSION, DAP_CHAIN_DATUM_TX) by str value
+ * @param a_type_str datum type in string value (token,emission,transaction)
+ * @return uint16_t 
+ */
 static uint16_t s_datum_type_from_str(const char *a_type_str)
 {
     if(!dap_strcmp(a_type_str, "token")) {
@@ -265,6 +277,12 @@ static uint16_t s_datum_type_from_str(const char *a_type_str)
     return DAP_CHAIN_DATUM_CUSTOM;
 }
 
+/**
+ * @brief s_chain_type_convert
+ * convert dap_chain_type_t to  DAP_CNAIN* constants
+ * @param a_type - dap_chain_type_t a_type [CHAIN_TYPE_TOKEN, CHAIN_TYPE_EMISSION, CHAIN_TYPE_TX]
+ * @return uint16_t 
+ */
 static uint16_t s_chain_type_convert(dap_chain_type_t a_type)
 {
     switch (a_type) {
@@ -281,10 +299,12 @@ static uint16_t s_chain_type_convert(dap_chain_type_t a_type)
 
 /**
  * @brief dap_chain_load_from_cfg
- * @param a_chain_net_name
- * @param a_chain_net_id
- * @param a_chain_cfg_path
- * @return
+ * Loading chain from config file
+ * @param a_ledger - ledger object
+ * @param a_chain_net_name - chain name, taken from config, for example - "home21-network"
+ * @param a_chain_net_id - dap_chain_net_id_t chain network identification
+ * @param a_chain_cfg_name chain config name, for example "network/home21-network/chain-0"
+ * @return dap_chain_t* 
  */
 dap_chain_t * dap_chain_load_from_cfg(dap_ledger_t* a_ledger, const char * a_chain_net_name,dap_chain_net_id_t a_chain_net_id, const char * a_chain_cfg_name)
 {
diff --git a/modules/chain/dap_chain_cell.c b/modules/chain/dap_chain_cell.c
index 74cc658e77..b28fc24733 100644
--- a/modules/chain/dap_chain_cell.c
+++ b/modules/chain/dap_chain_cell.c
@@ -54,10 +54,9 @@ typedef struct dap_chain_cell_file_header
 } DAP_ALIGN_PACKED dap_chain_cell_file_header_t;
 
 
-//static const char* s_cells_path = NULL;
-
 /**
  * @brief dap_chain_cell_init
+ * current version simply returns 0
  * @return
  */
 int dap_chain_cell_init(void)
@@ -66,6 +65,13 @@ int dap_chain_cell_init(void)
     return  0;
 }
 
+/**
+ * @brief dap_chain_cell_find_by_id
+ * get dap_chain_cell_t object by cell (shard) id
+ * @param a_chain dap_chain_t object
+ * @param a_cell_id dap_chain_cell_id_t cell (shard) id
+ * @return dap_chain_cell_t* 
+ */
 dap_chain_cell_t * dap_chain_cell_find_by_id(dap_chain_t * a_chain, dap_chain_cell_id_t a_cell_id)
 {
     if (!a_chain->cells)
@@ -78,9 +84,11 @@ dap_chain_cell_t * dap_chain_cell_find_by_id(dap_chain_t * a_chain, dap_chain_ce
 }
 
 /**
- * @brief dap_chain_cell_create_fill
- * a_cell_id if <0 then not used
- * @return
+ * @brief 
+ * a_cell_id if < 0 then not used
+ * @param a_chain dap_chain_t object
+ * @param a_cell_id dap_chain_cell_id_t cell (shard) id
+ * @return dap_chain_cell_t* 
  */
 dap_chain_cell_t * dap_chain_cell_create_fill(dap_chain_t * a_chain, dap_chain_cell_id_t a_cell_id)
 {
@@ -95,6 +103,14 @@ dap_chain_cell_t * dap_chain_cell_create_fill(dap_chain_t * a_chain, dap_chain_c
     return l_cell;
 }
 
+/**
+ * @brief dap_chain_cell_create_fill2
+ * set l_cell->file_storage_path and l_cell->id.uint64 from name of chain. 
+ * For example, 0.dchaincell. 0 - chain id, dchaincell - name of file
+ * @param a_chain - chain object
+ * @param a_filename - chain filename, for example "0.dchaincell"
+ * @return dap_chain_cell_t* 
+ */
 dap_chain_cell_t * dap_chain_cell_create_fill2(dap_chain_t * a_chain, const char *a_filename)
 {
     dap_chain_cell_t * l_cell = DAP_NEW_Z(dap_chain_cell_t);
@@ -108,6 +124,11 @@ dap_chain_cell_t * dap_chain_cell_create_fill2(dap_chain_t * a_chain, const char
     return l_cell;
 }
 
+/**
+ * @brief
+ * close a_cell->file_storage file object
+ * @param a_cell dap_chain_cell_t object
+ */
 void dap_chain_cell_close(dap_chain_cell_t *a_cell)
 {
     if(!a_cell)
@@ -119,8 +140,9 @@ void dap_chain_cell_close(dap_chain_cell_t *a_cell)
 }
 
 /**
- * @brief dap_chain_cell_delete
- * @return
+ * @brief 
+ * free chain cell objects
+ * @param a_cell dap_chain_cell_t object
  */
 void dap_chain_cell_delete(dap_chain_cell_t *a_cell)
 {
@@ -146,8 +168,9 @@ void dap_chain_cell_delete(dap_chain_cell_t *a_cell)
 
 /**
  * @brief dap_chain_cell_load
- * @param a_chain
- * @param a_cell_file_path
+ * load cell file, which is pointed in a_cell_file_path variable, for example "0.dchaincell"
+ * @param a_chain dap_chain_t object
+ * @param a_cell_file_path contains name of chain, for example "0.dchaincell" 
  * @return
  */
 int dap_chain_cell_load(dap_chain_t * a_chain, const char * a_cell_file_path)
@@ -215,7 +238,12 @@ int dap_chain_cell_load(dap_chain_t * a_chain, const char * a_cell_file_path)
 
 /**
  * @brief s_cell_file_append
- * @param a_cell
+ * add atoms to selected chain
+ * @param a_cell - cell object. Contains file path to cell storage data, for example - "0.dchaincell"
+ * a_cell->chain contains 
+ *  name - "zerochain"
+ *  net_name - "kelvin-testnet"
+ *  filepath - "C:\\Users\\Public\\Documents\\cellframe-node\\var\\lib\\network\\kelvin-testnet\\zerochain\\/0.dchaincell"
  * @param a_atom
  * @param a_atom_size
  * @return
@@ -320,8 +348,9 @@ int dap_chain_cell_file_append( dap_chain_cell_t * a_cell, const void* a_atom, s
 }
 
 /**
- * @brief dap_chain_cell_file_update
- * @param a_cell
+ * @brief
+ * return dap_chain_cell_file_append(a_cell, NULL, 0);
+ * @param a_cell dap_chain_cell_t
  * @return
  */
 int dap_chain_cell_file_update( dap_chain_cell_t * a_cell)
diff --git a/modules/chain/dap_chain_cs.c b/modules/chain/dap_chain_cs.c
index 491a35002a..fefcca077c 100644
--- a/modules/chain/dap_chain_cs.c
+++ b/modules/chain/dap_chain_cs.c
@@ -63,8 +63,8 @@ void dap_chain_cs_deinit(void)
 
 /**
  * @brief dap_chain_class_add
- * @param a_cs_str
- * @param a_callback_init
+ * @param a_cs_str consensus name
+ * @param a_callback_init callback function
  */
 void dap_chain_cs_type_add (const char * a_cs_str,  dap_chain_callback_new_cfg_t a_callback_init)
 {
@@ -97,6 +97,7 @@ int dap_chain_cs_type_create(dap_chain_t * a_chain, dap_config_t * a_chain_cfg)
 
 /**
  * @brief dap_chain_cs_add
+ * add consensus [dag_pos, dag_poa, block_poa, none] to s_cs_callbacks linked list
  * @param a_cs_str
  * @param a_callback_init
  */
@@ -110,6 +111,9 @@ void dap_chain_cs_add (const char * a_cs_str,  dap_chain_callback_new_cfg_t a_ca
 
 /**
  * @brief dap_chain_cs_create
+ * 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
  * @return
diff --git a/modules/chain/dap_chain_ledger.c b/modules/chain/dap_chain_ledger.c
index 94208cc05f..61a5efab2c 100644
--- a/modules/chain/dap_chain_ledger.c
+++ b/modules/chain/dap_chain_ledger.c
@@ -205,6 +205,7 @@ static bool s_debug_more = false;
 
 /**
  * @brief dap_chain_ledger_init
+ * current function version set s_debug_more parameter, if it define in config, and returns 0
  * @return
  */
 int dap_chain_ledger_init()
@@ -215,6 +216,7 @@ int dap_chain_ledger_init()
 
 /**
  * @brief dap_chain_ledger_deinit
+ * nothing do
  */
 void dap_chain_ledger_deinit()
 {
@@ -222,7 +224,9 @@ void dap_chain_ledger_deinit()
 }
 
 /**
- * Create dap_ledger_t structure
+ * @brief dap_chain_ledger_handle_new
+ * Create empty dap_ledger_t structure
+ * @return dap_ledger_t* 
  */
 static dap_ledger_t * dap_chain_ledger_handle_new(void)
 {
@@ -240,7 +244,9 @@ static dap_ledger_t * dap_chain_ledger_handle_new(void)
 }
 
 /**
+ * @brief dap_chain_ledger_handle_free
  * Remove dap_ledger_t structure
+ * @param a_ledger 
  */
 void dap_chain_ledger_handle_free(dap_ledger_t *a_ledger)
 {
@@ -406,9 +412,12 @@ int dap_chain_ledger_token_add(dap_ledger_t * a_ledger,  dap_chain_datum_token_t
 
 /**
  * @brief s_token_tsd_parse
- * @param a_ledger
- * @param a_token
- * @param a_token_size
+ * 
+ * @param a_ledger 
+ * @param a_token_item 
+ * @param a_token 
+ * @param a_token_size 
+ * @return int 
  */
 static int s_token_tsd_parse(dap_ledger_t * a_ledger, dap_chain_ledger_token_item_t *a_token_item , dap_chain_datum_token_t * a_token, size_t a_token_size)
 {
diff --git a/modules/channel/chain/dap_stream_ch_chain.c b/modules/channel/chain/dap_stream_ch_chain.c
index 749d9e7969..6b142d3be7 100644
--- a/modules/channel/chain/dap_stream_ch_chain.c
+++ b/modules/channel/chain/dap_stream_ch_chain.c
@@ -447,9 +447,9 @@ static bool s_sync_update_gdb_proc_callback(dap_proc_thread_t *a_thread, void *a
 }
 
 /**
- * @brief s_chain_in_pkt_callback
- * @param a_thread
- * @param a_arg
+ * @brief s_sync_in_chains_callback
+ * @param a_thread dap_proc_thread_t
+ * @param a_arg void
  * @return
  */
 static bool s_sync_in_chains_callback(dap_proc_thread_t *a_thread, void *a_arg)
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 3613d3acf0..a2fa8abdab 100644
--- a/modules/consensus/dag-poa/dap_chain_cs_dag_poa.c
+++ b/modules/consensus/dag-poa/dap_chain_cs_dag_poa.c
@@ -260,9 +260,10 @@ static int s_callback_new(dap_chain_t * a_chain, dap_config_t * a_chain_cfg)
 }
 
 /**
- * @brief s_callback_created
- * @param a_chain
- * @param 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 
  * @return
  */
 static int s_callback_created(dap_chain_t * a_chain, dap_config_t *a_chain_net_cfg)
diff --git a/modules/consensus/dag-pos/dap_chain_cs_dag_pos.c b/modules/consensus/dag-pos/dap_chain_cs_dag_pos.c
index 4e66d0704e..e0bf1f66e3 100644
--- a/modules/consensus/dag-pos/dap_chain_cs_dag_pos.c
+++ b/modules/consensus/dag-pos/dap_chain_cs_dag_pos.c
@@ -182,12 +182,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 
+ * create event
+ * @param a_dag 
+ * @param a_datum 
+ * @param a_hashes 
+ * @param a_hashes_count 
+ * @param a_dag_event_size 
+ * @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,
@@ -210,10 +212,12 @@ static dap_chain_cs_dag_event_t * s_callback_event_create(dap_chain_cs_dag_t * a
 }
 
 /**
- * @brief s_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/consensus/none/dap_chain_cs_none.c b/modules/consensus/none/dap_chain_cs_none.c
index a4ece1bc76..92bac8ef53 100644
--- a/modules/consensus/none/dap_chain_cs_none.c
+++ b/modules/consensus/none/dap_chain_cs_none.c
@@ -107,6 +107,7 @@ static int s_cs_callback_new(dap_chain_t * a_chain, dap_config_t * a_chain_cfg)
 
 /**
  * @brief dap_chain_cs_gdb_init
+ * Initialize GDB chain items organization class
  * @return
  */
 int dap_chain_gdb_init(void)
diff --git a/modules/net/dap_chain_net.c b/modules/net/dap_chain_net.c
index cebea33c10..c5aae9dbe1 100644
--- a/modules/net/dap_chain_net.c
+++ b/modules/net/dap_chain_net.c
@@ -978,12 +978,12 @@ dap_chain_node_role_t dap_chain_net_get_role(dap_chain_net_t * a_net)
 }
 
 /**
- * @brief dap_chain_net_new
- * @param a_id
- * @param a_name
- * @param a_node_role
- * @param a_node_name
- * @return
+ * @brief set node role
+ * [root_master, root, archive, cell_master, master, full, light]
+ * @param a_id 
+ * @param a_name 
+ * @param a_node_role 
+ * @return dap_chain_net_t* 
  */
 static dap_chain_net_t *s_net_new(const char * a_id, const char * a_name ,
                                     const char * a_node_role)
@@ -1046,6 +1046,7 @@ static dap_chain_net_t *s_net_new(const char * a_id, const char * a_name ,
 
 /**
  * @brief dap_chain_net_delete
+ * free dap_chain_net_t * a_net object
  * @param a_net
  */
 void dap_chain_net_delete( dap_chain_net_t * a_net )
@@ -1579,9 +1580,11 @@ static int callback_compare_prioritity_list(const void * a_item1, const void * a
 }
 
 /**
- * @brief s_net_load
- * @param a_net_name
- * @return
+ * @brief load network config settings from cellframe-node.cfg file
+ * 
+ * @param a_net_name const char *: network name, for example "home21-network"
+ * @param a_acl_idx currently 0
+ * @return int 
  */
 int s_net_load(const char * a_net_name, uint16_t a_acl_idx)
 {
@@ -2516,6 +2519,10 @@ bool dap_chain_net_get_add_gdb_group(dap_chain_net_t *a_net, dap_chain_node_addr
 
 /**
  * @brief dap_chain_net_verify_datum_for_add
+ * process datum verification process. Can be:
+ *   if DAP_CHAIN_DATUM_TX, called dap_chain_ledger_tx_add_check
+ *   if DAP_CHAIN_DATUM_TOKEN_DECL, called dap_chain_ledger_token_decl_add_check
+ *   if DAP_CHAIN_DATUM_TOKEN_EMISSION, called dap_chain_ledger_token_emission_add_check
  * @param a_net
  * @param a_datum
  * @return
diff --git a/modules/net/dap_chain_node.c b/modules/net/dap_chain_node.c
index e06be2f212..4340c4b31e 100644
--- a/modules/net/dap_chain_node.c
+++ b/modules/net/dap_chain_node.c
@@ -254,6 +254,12 @@ bool dap_chain_node_mempool_process(dap_chain_t *a_chain, dap_chain_node_role_t
 
 static bool s_mempool_auto = false;
 
+/**
+ * @brief 
+ * get automatic mempool processing, when network config contains mempool_auto_types for specific datums
+ * @return true 
+ * @return false 
+ */
 bool dap_chain_node_mempool_autoproc_init()
 {
     uint16_t l_net_count;
diff --git a/modules/net/dap_chain_node_cli_cmd.c b/modules/net/dap_chain_node_cli_cmd.c
index 3c9cb9e875..5c2fcbe166 100644
--- a/modules/net/dap_chain_node_cli_cmd.c
+++ b/modules/net/dap_chain_node_cli_cmd.c
@@ -2308,6 +2308,7 @@ int com_mempool_delete(int argc, char ** argv, void *arg_func, char ** a_str_rep
 
 /**
  * @brief com_mempool_proc
+ * process mempool datums
  * @param argc
  * @param argv
  * @param arg_func
-- 
GitLab