Diff: include/mydsc_kvp.h

Revision:

2:1f276b0dd807

Parent:

1:2c47778e8a67

Child:

4:90c3f1288d41

--- a/include/mydsc_kvp.h	Fri Feb 28 20:06:30 2020 +0000
+++ b/include/mydsc_kvp.h	Wed Mar 04 13:38:48 2020 +0000
@@ -1,5 +1,7 @@
 /** @file: mydsc_kvp.h
     @author Gastón H. Salazar-Silva <gaston_salazar@yahoo.com>
+    
+    @brief A very basic key-value pair system is implemented. 
 **/
 
 #ifndef MYDSC_kvp_H
@@ -11,6 +13,7 @@
 extern "C" {
 #endif
 
+/// Error conditions on looking-up a key, or trying to setting the value.
 enum mydsc_kvp_errno_t {
     MYDSC_KVP_SUCCESS       = 0,
     MYDSC_KVP_NO_SET        = -1,
@@ -18,6 +21,7 @@
     MYDSC_KVP_WRONG_VALUE   = -3                
 };
 
+/// The structure sets a linked list up.
 typedef struct mydsc_kvp_struct {
     char *key;
     char* (*get_function)(void);
@@ -25,9 +29,29 @@
     struct mydsc_kvp_struct *next_kvp;
 } mydsc_kvp_t;
 
+/// Initialize the linked list, then puts a first key ("version")
+/// @param pkv is a pointer to the linked list. 
 int mydsc_kvp_init(mydsc_kvp_t* pkv);
+
+/// Returns the value associated with a key.
+/// @param pkv is a pointer to the linked list. 
+/// @param key  is a character string to look-up in the linked list.
+/// @return The value associated to the key, as a character string. 
 char* mydsc_kvp_get_value(mydsc_kvp_t* pkv, char* key);
+
+/// Sets or change the value associated with a key.
+/// @param pkv is a pointer to the linked list. 
+/// @param key  is a character string to look-up in the linked list.
+/// @param value is the new setting, encoded as a character string.
+/// @return an error encoded as a mydsc_kvp_errno_t.
 int mydsc_kvp_set_value(mydsc_kvp_t* pkv, char* key, char* value);
+
+/// Appends a new key-value pair into the linked list.
+/// @param pkv is a pointer to the linked list. 
+/// @param key  is a character string to look-up in the linked list.
+/// @param get_function is a pointer to a function.
+/// @param set_function is a pointer to a function.
+/// @return an error encoded as a mydsc_kvp_errno_t.
 int mydsc_kvp_append(mydsc_kvp_t* pkv, char* key,
                     char* (*get_function)(void),
                     int (*set_function)(char*));