Add missing documentation. Add more error checks.

doc/CMakeLists.txt

@@ -105,6 +105,7 @@ if (DOXYGEN_FOUND)
         ${CMAKE_SOURCE_DIR}/mentos/inc/version.h
 
         ${CMAKE_SOURCE_DIR}/mentos/src/boot.c
+        ${CMAKE_SOURCE_DIR}/mentos/src/crypt/sha256.c
         ${CMAKE_SOURCE_DIR}/mentos/src/descriptor_tables/exception.c
         ${CMAKE_SOURCE_DIR}/mentos/src/descriptor_tables/gdt.c
         ${CMAKE_SOURCE_DIR}/mentos/src/descriptor_tables/idt.c
@@ -193,6 +194,7 @@ if (DOXYGEN_FOUND)
         ${CMAKE_SOURCE_DIR}/libc/inc/bits/ioctls.h
         ${CMAKE_SOURCE_DIR}/libc/inc/bits/stat.h
         ${CMAKE_SOURCE_DIR}/libc/inc/bits/termios-struct.h
+        ${CMAKE_SOURCE_DIR}/libc/inc/crypt/sha256.h
         ${CMAKE_SOURCE_DIR}/libc/inc/ctype.h
         ${CMAKE_SOURCE_DIR}/libc/inc/fcntl.h
         ${CMAKE_SOURCE_DIR}/libc/inc/fcvt.h
@@ -259,6 +261,7 @@ if (DOXYGEN_FOUND)
         ${CMAKE_SOURCE_DIR}/libc/src/sys/utsname.c
         ${CMAKE_SOURCE_DIR}/libc/src/termios.c
         ${CMAKE_SOURCE_DIR}/libc/src/time.c
+        ${CMAKE_SOURCE_DIR}/libc/src/crypt/sha256.c
         ${CMAKE_SOURCE_DIR}/libc/src/unistd/chdir.c
         ${CMAKE_SOURCE_DIR}/libc/src/unistd/close.c
         ${CMAKE_SOURCE_DIR}/libc/src/unistd/creat.c

libc/inc/crypt/sha256.h

@@ -1,9 +1,8 @@
-/// @file sha256.c
-/// @author Enrico Fraccaroli ([email protected])
+/// @file sha256.h
 /// @brief Implementation of the SHA-256 hashing algorithm.
 /// @details The original code was written by Brad Conte, and is available at:
 ///     https://github.com/B-Con/crypto-algorithms
-/// 
+///
 /// SHA-256 is one of the three algorithms in the SHA2
 /// specification. The others, SHA-384 and SHA-512, are not
 /// offered in this implementation.
@@ -19,14 +18,33 @@
 /// @brief SHA256 outputs a 32 byte digest.
 #define SHA256_BLOCK_SIZE 32
 
+/// @brief Structure that holds context information for SHA-256 operations.
 typedef struct {
-    uint8_t data[64];
-    uint32_t datalen;
-    unsigned long long bitlen;
-    uint32_t state[8];
+    uint8_t data[64];          ///< Input data block being processed (512 bits / 64 bytes).
+    uint32_t datalen;          ///< Length of the current data in the buffer (in bytes).
+    unsigned long long bitlen; ///< Total length of the input in bits (for padding).
+    uint32_t state[8];         ///< Current hash state (256 bits / 8 * 32-bit words).
 } SHA256_ctx_t;
 
+/// @brief Initializes the SHA-256 context.
+/// @param ctx Pointer to the SHA-256 context to initialize.
 void sha256_init(SHA256_ctx_t *ctx);
+
+/// @brief Adds data to the SHA-256 context for hashing.
+/// @param ctx Pointer to the SHA-256 context.
+/// @param data Pointer to the data to be hashed.
+/// @param len Length of the data to hash, in bytes.
 void sha256_update(SHA256_ctx_t *ctx, const uint8_t data[], size_t len);
+
+/// @brief Finalizes the hashing and produces the final SHA-256 digest.
+/// @param ctx Pointer to the SHA-256 context.
+/// @param hash Pointer to a buffer where the final hash will be stored (must be at least 32 bytes long).
 void sha256_final(SHA256_ctx_t *ctx, uint8_t hash[]);
+
+/// @brief Converts a byte array to its hexadecimal string representation.
+/// @param src Pointer to the source byte array.
+/// @param src_length Length of the source byte array.
+/// @param out Pointer to the output buffer for the hexadecimal string.
+/// @param out_length Length of the output buffer (must be at least 2 * src_length + 1).
+/// @details The output string will be null-terminated if the buffer is large enough.
 void sha256_bytes_to_hex(uint8_t *src, size_t src_length, char *out, size_t out_length);

libc/inc/readline.h

@@ -5,10 +5,12 @@
 
 #include "stddef.h"
 
-/// @brief Reads a line from the file.
-/// @param fd the file descriptor.
-/// @param buffer the buffer where we place the line.
-/// @param buflen the length of the buffer.
-/// @param readlen the amount we read, if negative, we did not encounter a newline.
-/// @return 0 if we are done reading, 1 if we encountered a newline, -1 if otherwise.
+/// @brief Reads a line from the given file descriptor into the buffer.
+/// @param fd The file descriptor to read from.
+/// @param buffer The buffer where the read line will be stored. Must not be NULL.
+/// @param buflen The size of the buffer.
+/// @param read_len A pointer to store the length of the read line. Can be NULL if not needed.
+/// @return 1 if a newline was found and the line was read successfully, 
+///         0 if the end of the file was reached, 
+///        -1 if no newline was found and partial data was read.
 int readline(int fd, char *buffer, size_t buflen, ssize_t *read_len);

libc/inc/sys/list_head_algorithm.h

@@ -1,5 +1,4 @@
 /// @file list_head_algorithm.h
-/// @author Enrico Fraccaroli ([email protected])
 /// @brief Some general algorithm that might come in handy while using list_head.
 /// @copyright (c) 2014-2024 This file is distributed under the MIT License.
 /// See LICENSE.md for details.

libc/inc/sys/mman.h

@@ -1,5 +1,4 @@
 /// @file mman.h
-/// @author Enrico Fraccaroli ([email protected])
 /// @brief Functions for managing mappings in virtual address space.
 /// @copyright (c) 2014-2024 This file is distributed under the MIT License.
 /// See LICENSE.md for details.