Added hash table documentation

8 files changed, 45 insertions, 4 deletions

diff --git a/src/ht/ft_htcontent_new.c b/src/ht/ft_htcontent_new.c
index 214e125..7dd4f20 100644
--- a/src/ht/ft_htcontent_new.c
+++ b/src/ht/ft_htcontent_new.c
@@ -13,6 +13,12 @@
 #include "libft.h"
 #include "libft_ht.h"
 
+/*
+** Create a new hash table key/value pair.
+** `key` is always duplicated.
+** Return a pointer to the created content or NULL is an allocation failed.
+*/
+
 t_ftht_content	*ft_htcontent_new(char *key, void *value)
 {
 	t_ftht_content	*content;
diff --git a/src/ht/ft_htdelone.c b/src/ht/ft_htdelone.c
index 77eae58..e3bb355 100644
--- a/src/ht/ft_htdelone.c
+++ b/src/ht/ft_htdelone.c
@@ -13,6 +13,10 @@
 #include "libft.h"
 #include "libft_ht.h"
 
+/*
+** Delete one hash table entry at `key`.
+*/
+
 void	ft_htdelone(t_ftht *ht, char *key, void (*del)(t_ftht_content*))
 {
 	ft_lstremove_if(ht->entries + ft_hthash(ht, key),
diff --git a/src/ht/ft_htdestroy.c b/src/ht/ft_htdestroy.c
index 900f76e..a788a78 100644
--- a/src/ht/ft_htdestroy.c
+++ b/src/ht/ft_htdestroy.c
@@ -13,6 +13,11 @@
 #include "libft.h"
 #include "libft_ht.h"
 
+/*
+** Destroy an hash table.
+** The `del` function is used to destroy each key/value pair
+*/
+
 void	ft_htdestroy(t_ftht *ht, void (*del)(t_ftht_content*))
 {
 	if (ht == NULL)
diff --git a/src/ht/ft_htget.c b/src/ht/ft_htget.c
index 1562eb0..94a4164 100644
--- a/src/ht/ft_htget.c
+++ b/src/ht/ft_htget.c
@@ -13,9 +13,14 @@
 #include "libft.h"
 #include "libft_ht.h"
 
+/*
+** Retrieve a value with associated key.
+** Returns NULL if there is no value at `key`.
+*/
+
 void	*ft_htget(t_ftht *ht, char *key)
 {
-	
+
 	t_ftht_digest	digest;
 	t_ftlst			*found;
 
diff --git a/src/ht/ft_hthash.c b/src/ht/ft_hthash.c
index e7e696c..ba922e7 100644
--- a/src/ht/ft_hthash.c
+++ b/src/ht/ft_hthash.c
@@ -12,6 +12,11 @@
 
 #include "libft_ht.h"
 
+/*
+** Hash a string according to the size of the hash table.
+*/
+
+// maybe use a less efficient but understandable function
 t_ftht_digest	ft_hthash(t_ftht *ht, char *key)
 {
 	t_ftht_digest	digest;
diff --git a/src/ht/ft_htnew.c b/src/ht/ft_htnew.c
index 6827c36..465eabf 100644
--- a/src/ht/ft_htnew.c
+++ b/src/ht/ft_htnew.c
@@ -13,6 +13,12 @@
 #include "libft.h"
 #include "libft_ht.h"
 
+/*
+** Create a new hash table.
+** `size` is the size of the underlying array of linked list (buckets)
+** Return NULL is an allocation failed.
+*/
+
 t_ftht	*ft_htnew(t_ftsize size)
 {
 	t_ftht	*ht;
diff --git a/src/ht/ft_htset.c b/src/ht/ft_htset.c
index 81aba97..0755889 100644
--- a/src/ht/ft_htset.c
+++ b/src/ht/ft_htset.c
@@ -13,6 +13,13 @@
 #include "libft.h"
 #include "libft_ht.h"
 
+/*
+** Create/Update a entry in an hash table.
+** If `key` already exist in `ht`, updates only the list element content.
+** else create a new list node in addition the list content.
+** Return a pointer to the created entry, NULL if an allocation failed.
+*/
+
 t_ftht_content	*ft_htset(t_ftht *ht, char *key, void *value,
 							void (*del)(t_ftht_content*))
 {
@@ -30,14 +37,13 @@ t_ftht_content	*ft_htset(t_ftht *ht, char *key, void *value,
 	if (tmp != NULL)
 	{
 		if (del != NULL)
-			(*del)(tmp->content);
+			del(tmp->content);
 		tmp->content = content;
 		return ((t_ftht_content*)tmp->content);
 	}
-
 	if ((entry = ft_lstnew(content)) == NULL)
 	{
-		free(content);
+		del(content);
 		return (NULL);
 	}
 	ft_lstadd_front(ht->entries + digest, entry);
diff --git a/src/ht/ft_inter_htkey_cmp.c b/src/ht/ft_inter_htkey_cmp.c
index be2e52f..397177e 100644
--- a/src/ht/ft_inter_htkey_cmp.c
+++ b/src/ht/ft_inter_htkey_cmp.c
@@ -13,6 +13,10 @@
 #include "libft.h"
 #include "libft_ht.h"
 
+/*
+** Hash table internal function to compare key string in linked list.
+*/
+
 int	ft_inter_htkey_cmp(const void *ref_key, const void *content)
 {
 	if (ref_key == NULL || content == NULL)