📝 (doxygen): Added Doxygen documentation

.gitignore

@@ -55,3 +55,4 @@ build
 .direnv
 result
 /debug.c
+a.py

CMakeLists.txt

@@ -1,9 +1,16 @@
 cmake_minimum_required(VERSION 3.10)
 
-project(tinyhash VERSION 0.0.1 LANGUAGES C DESCRIPTION "Simple C hash table implementation.")
+project(tinyhash VERSION 0.0.1 LANGUAGES C DESCRIPTION "This is a library containing multiple C implementations of hashmap.")
+
+option(BUILD_TESTS "Build the tests" OFF)
+option(BUILD_DOC "Build the documentation" OFF)
 
 add_subdirectory(src)
 
 if (BUILD_TESTS)
     add_subdirectory(tests)
 endif ()
+
+if (BUILD_DOC)
+    add_subdirectory(doc)
+endif ()

README.md

@@ -34,6 +34,7 @@ The following CMake build arguments are available to enable or disable options.
 | -- | -- | -- |
 | `-DBUILD_TESTS` | Compile the test files | **`ON`**
 | `-DBUILD_STATIC` | Link as a static library (instead of a shared library) | **`OFF`**
+| `-DBUILD_DOC` | Build the documentation | **`OFF`**
 
 ## 🤝 Contribute
 
@@ -48,6 +49,12 @@ The generated Makefile will contain a special `test` target, so you can run the
 make test
 ```
 
+## 📝 Documentation
+
+Just make sure you run CMake with the `-DBUILD_DOC=ON` flag.
+
+The Makefile `all` target will automatically build the documentation.
+
 ## 📎 Some examples
 
 Here is a basic example of how you could use the hashmap.

default.nix

@@ -2,9 +2,12 @@
   stdenv,
   lib,
   cmake,
+  doxygen,
+  graphviz,
   enableStatic ? false,
   enableShared ? !enableStatic,
   enaleTests ? true,
+  enableDoc ? true,
 }:
 
 assert enableShared || enableStatic;
@@ -17,16 +20,30 @@ stdenv.mkDerivation (finalAttrs: {
 
   cmakeFlags =
     lib.optional enaleTests "-DBUILD_TESTS=ON"
-    ++ lib.optional enableStatic "-DBUILD_STATIC=ON";
+    ++ lib.optional enableStatic "-DBUILD_STATIC=ON"
+    ++ lib.optional enableDoc ''
+      -DBUILD_DOC=ON
+      -DDOT_BIN_PATH=${graphviz}/bin/dot
+    '';
 
   nativeBuildInputs = [ cmake ];
 
-  postBuild = ''
+  buildInputs = [ doxygen ];
+
+  postBuild = lib.optionals enaleTests ''
     make test
   '';
 
+  postInstall = lib.optionals enaleTests ''
+    mkdir $out/doc
+
+    for dir in "html" "latex"; do
+      mv doc/$dir $out/doc/$dir
+    done
+  '';
+
   meta = {
-    description = "Simple C hash table implementation.";
+    description = "This is a library containing multiple C implementations of hashmap.";
     homepage = "https://github.com/theobori/${finalAttrs.pname}";
     license = lib.licenses.mit;
   };

doc/CMakeLists.txt

@@ -0,0 +1,41 @@
+find_package(Doxygen)
+
+
+find_program(DOT_BIN NAMES dot)
+
+if(DOT_BIN)
+	set(DOT_BIN_PATH "${DOT_BIN}" CACHE PATH "Path to dot")
+else()
+	set(DOT_BIN_PATH "" CACHE PATH "Path to dot")
+endif()
+
+if(DOXYGEN_FOUND)
+    message(STATUS "Doxygen found: ${DOXYGEN_EXECUTABLE} -- ${DOXYGEN_VERSION}")
+
+	# set Doxygen input and output files.
+	set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src)
+	set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+	set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
+	set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+	set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+
+	# Generate DoxyFile from the input file.
+	configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+	# Create Output directory.
+	file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+
+
+	# Command for generating doc from Doxygen config file.
+	add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+					COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+					MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+					COMMENT "Generating Doxygen documentation"
+					VERBATIM)
+
+
+	# Create CMake Target for generating doc.
+	add_custom_target(docs ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+endif()

doc/Doxyfile.in

@@ -0,0 +1,35 @@
+PROJECT_NAME           = "Tinyhash"
+PROJECT_BRIEF          = "This is a library containing multiple C implementations of hashmap."
+EXTRACT_ALL            = YES
+DISTRIBUTE_GROUP_DOC   = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_PACKAGE        = YES
+EXTRACT_STATIC         = YES
+EXTRACT_ANON_NSPACES   = YES
+WARN_NO_PARAMDOC       = YES
+RECURSIVE              = YES
+SOURCE_BROWSER         = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = NO
+GENERATE_TREEVIEW      = NO
+
+HAVE_DOT               = YES
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_PATH               = "@DOT_BIN_PATH@"
+
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = YES
+TEMPLATE_RELATIONS     = YES
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+DIRECTORY_GRAPH        = YES
+DOT_CLEANUP            = YES
+
+INPUT                  = "@DOXYGEN_INPUT_DIR@" @PROJECT_SOURCE_DIR@/README.md
+USE_MDFILE_AS_MAINPAGE = "@PROJECT_SOURCE_DIR@/README.md"

flake.nix

@@ -31,6 +31,8 @@
             packages = with pkgs; [
               cmake
               clang
+              doxygen
+              graphviz
             ];
           };
         }

src/common/hash.c

@@ -1,7 +1,16 @@
 #include <stdint.h>
 #include <stdlib.h>
 
+/**
+ * @brief Initial value for hash function.
+ *
+ */
 #define TH_HASH_INITIAL_VALUE 2166136261u
+
+/**
+ * @brief Multiplier for hash function.
+ *
+ */
 #define TH_HASH_MUL_VALUE 16777619
 
 uint32_t th_hash(uint8_t *bytes, size_t size) {

src/common/hash.h

@@ -4,6 +4,13 @@
 #include <stdint.h>
 #include <stdio.h>
 
+/**
+ * @brief Compute an unsigned int from bytes.
+ *
+ * @param bytes
+ * @param size
+ * @return uint32_t
+ */
 uint32_t th_hash(uint8_t *bytes, size_t size);
 
 #endif

src/common/key.c

@@ -1,8 +1,7 @@
-#include "key.h"
-
 #include <string.h>
 
 #include "hash.h"
+#include "key.h"
 
 th_key_t th_key_create(th_any_t data, size_t size) {
   return (th_key_t){
@@ -13,6 +12,9 @@ th_key_t th_key_create(th_any_t data, size_t size) {
 }
 
 bool th_key_is_equal(th_key_t *first, th_key_t *second) {
+  if (first == NULL || second == NULL)
+    return false;
+
   if (first->size != second->size)
     return false;
 

src/common/key.h

@@ -7,14 +7,34 @@
 
 #include "types.h"
 
+/**
+ * @brief Represent an entry key.
+ *
+ */
 typedef struct {
   uint32_t hash;
   size_t size;
   th_any_t data;
 } th_key_t;
 
+/**
+ * @brief Create a key struct from data and size, it will automatically
+ * compute its hash.
+ *
+ * @param data
+ * @param size
+ * @return th_key_t
+ */
 th_key_t th_key_create(th_any_t data, size_t size);
 
+/**
+ * @brief Key comparator function.
+ *
+ * @param first
+ * @param second
+ * @return true
+ * @return false
+ */
 bool th_key_is_equal(th_key_t *first, th_key_t *second);
 
 #endif

src/common/table.h

@@ -1,6 +1,10 @@
 #ifndef __TINYHASH_COMMON_TABLE_H__
 #define __TINYHASH_COMMON_TABLE_H__
 
+/**
+ * @brief Generate the next capacity value absed on a previous one.
+ *
+ */
 #define TH_TABLE_NEXT_CAPACITY(capacity) (capacity) == 0 ? 8 : (capacity) * 2
 
 #endif

src/common/types.h

@@ -1,8 +1,16 @@
 #ifndef __TINYHASH_COMMON_TYPES_H__
 #define __TINYHASH_COMMON_TYPES_H__
 
+/**
+ * @brief Represent any type of data.
+ *
+ */
 typedef void *th_any_t;
 
+/**
+ * @brief Represents any table.
+ *
+ */
 typedef void *th_generic_table_t;
 
 #endif

src/open_addressing/entry.h

@@ -8,6 +8,10 @@
 #include "../common/hash.h"
 #include "../common/key.h"
 
+/**
+ * @brief Represent an entry within a bucket.
+ *
+ */
 typedef struct th_oa_entry_s {
   th_key_t *key;
   th_any_t value;

src/open_addressing/table.c

@@ -17,6 +17,12 @@ void th_oa_table_init(th_oa_table_t *table) {
   table->entries = NULL;
 }
 
+/**
+ * @brief Allocate then initialize an open addressing table.
+ * It can return NULL.
+ *
+ * @return th_oa_table_t*
+ */
 static th_oa_table_t *_th_oa_table_create() {
   th_oa_table_t *table = malloc(sizeof(th_oa_table_t));
 
@@ -32,6 +38,15 @@ th_generic_table_t th_oa_table_create() {
   return (th_generic_table_t)_th_oa_table_create();
 }
 
+/**
+ * @brief Copy and rehash every value from a table to another.
+ * Return true on success.
+ *
+ * @param dest
+ * @param src
+ * @return true
+ * @return false
+ */
 static bool th_oa_table_copy(th_oa_table_t *dest, th_oa_table_t *src) {
   bool success;
 
@@ -50,6 +65,13 @@ static bool th_oa_table_copy(th_oa_table_t *dest, th_oa_table_t *src) {
   return true;
 }
 
+/**
+ * @brief Increase the size of a table.
+ *
+ * @param table
+ * @return true
+ * @return false
+ */
 static bool th_oa_table_increase(th_oa_table_t *table) {
   th_oa_table_t new_table;
   bool success;
@@ -77,6 +99,14 @@ static bool th_oa_table_increase(th_oa_table_t *table) {
   return true;
 }
 
+/**
+ * @brief Returns a bucket (entry) depending on a key.
+ * It can return a tomstone or an empty bucket.
+ *
+ * @param table
+ * @param key
+ * @return th_oa_entry_t*
+ */
 static th_oa_entry_t *th_oa_table_find(th_oa_table_t *table, th_key_t *key) {
   int index = key->hash % table->capacity;
 
@@ -113,9 +143,18 @@ th_any_t th_oa_table_get(th_generic_table_t generic_table, th_any_t data,
   return entry->value;
 }
 
+/**
+ * @brief Insert a value within the table with an already existing key.
+ *
+ * @param table
+ * @param key
+ * @param value
+ * @return true
+ * @return false
+ */
 static bool th_oa_table_put_with_key(th_oa_table_t *table, th_key_t *key,
                                      th_any_t value) {
-  if (table->count >= (table->capacity * TH_OA_LOAD_FACTOR)) {
+  if (table->count >= table->capacity * TH_OA_LOAD_FACTOR) {
     if (th_oa_table_increase(table) == false)
       return false;
   }
@@ -139,6 +178,9 @@ static bool th_oa_table_put_with_key(th_oa_table_t *table, th_key_t *key,
 
 bool th_oa_table_put(th_generic_table_t generic_table, th_any_t data,
                      size_t data_size, th_any_t value) {
+  if (generic_table == NULL)
+    return NULL;
+
   th_oa_table_t *table = (th_oa_table_t *)generic_table;
   th_key_t key = th_key_create(data, data_size);