[FEATURE REQUEST] Enhance In-Code Documentation with Algorithm and Complexity Analysis of DLL

[FatinShadab]

Describe the feature

Requested Task

The current in-code documentation (using Doxygen-style comments, as seen in dll.h) is excellent for describing what a function does. However, to make C-STRUCTURE a more comprehensive educational and resource-full repository for developers, we should enhance the documentation to explain how the function works, its performance characteristics, and its resource usage.

I request that we update the in-code documentation template to include the Algorithm, Time Complexity, and Space Complexity for every function implementation across all Doubly Linked List header/source files (specifically, focusing on dll.h and its related source, dll.c).

It should be implemented because

Using the insertAtHead__int function as an example, the documentation should be extended as follows:

// dll.c
// -------------------------------------------------------------------------------------------->
// FUNCTION TO INSERT DATA TO DLL : HEAD
// -------------------------------------------------------------------------------------------->
/**
 * @brief Inserts a new node with the given data at the head of the doubly linked list.
 *
 * This function creates a new node with the provided data and inserts it at the beginning
 * of the given doubly linked list. If the linked list is empty, the new node becomes both
 * the head and the tail of the list. If the list is not empty, the new node becomes the
 * head, and its next pointer is set to the previous head node, effectively making it the
 * first node in the list. Also, the previous pointer of the old head node is updated to
 * point to the new node.
 *
 * @param dll Pointer to the doubly linked list structure.
 * @param data Data to be inserted into the linked list.
 *
 * @return void
 *
 * // --- NEW SECTIONS BELOW ---
 * @algorithm
 * 1. Allocate memory for a new node.
 * 2. Assign the input data to the new node.
 * 3. Set the new node's previous pointer to NULL.
 * 4. Check if the list is empty (head is NULL).
 * 5. If empty: set the new node's next pointer to NULL, and set the new node as both the head and the tail.
 * 6. If not empty: set the new node's next pointer to the current head, and update the current head's previous pointer to the new node.
 * 7. Update the list's head to be the new node.
 * 8. Increment the list size.
 * 
 *
 * @complexity
 * - Time: O(1) - The operation involves a fixed number of steps (memory allocation, pointer manipulation) regardless of the list size.
 * - Space: O(1) - A single new node is allocated, making the space requirement constant relative to the list size.
 *
 * @note The function updates the size, head, and tail pointers of the linked list accordingly.
 */
void insertAtHead__int(DLL__int *dll, int data) {
    struct DLLNode__int *node = (struct DLLNode__int *) malloc(sizeof(struct DLLNode__int));

    node->data = data;
    node->prev = NULL;

    dll->size++;

    if (dll->head == NULL) {
        node->next = NULL;
        dll->head = node;
        dll->tail = node;
        return;
    }

    node->next = dll->head;
    dll->head->prev = node;
    dll->head = node;
}

Benefits

• Educational Value: Developers, especially beginners, can immediately understand the efficiency and underlying mechanism of the data structure operation, particularly how the two pointers (next and prev) are managed.
• Performance Insight: Provides experienced developers with quick performance characteristics for integrating the functions into their projects.
• Consistency: Establishes a higher standard for documentation throughout the repository, aligning DLL with SLL standards.

Additional context

No response

Would you like to work on this issue?

None

[Siddhatho]

its pleasure to work on this great project ,
i will give update very soon