Improve LeetCode-style docstrings in list tasks

Author: djeada

src/4_Lists/clone_complex_list.cpp

@@ -1,33 +1,25 @@
 /*
  * Task: Deep copy a linked list with sibling pointers.
  *
- * DEEP COPY OF A COMPLEX LINKED LIST WITH SIBLING POINTERS
+ * COPY LIST WITH RANDOM (SIBLING) POINTER
  *
- * Define a class named ComplexList that represents a singly linked list where
- * each node has an integer value, a pointer to the next node, and an additional
- * "sibling" pointer that can reference any other node in the list. The class
- * supports operations for appending nodes, setting sibling pointers, and
- * performing a deep copy of the entire list while preserving the sibling
- * relationships.
+ * Problem:
+ * Given a linked list where each node has `next` and `sibling` pointers,
+ * create a deep copy of the list. The copied nodes must be new objects, and
+ * every copied sibling pointer must reference the corresponding copied node.
  *
- * ASCII Illustration:
+ * Constraints:
+ * - 0 <= n <= 10^5
+ * - Node values are 32-bit signed integers.
+ * - `sibling` is either null or points to any node in the same list.
  *
- *    Original List:      Copied List:
+ * Example 1:
+ * Input: values = [1,2,3,4,5], sibling = {1->3, 2->5, 5->2}
+ * Output: deep-copied list with identical `next` and `sibling` structure
  *
- *      1  -->  2  -->  3       1  -->  2  -->  3
- *       \       \              \       \
- *        v       v              v       v
- *        3       5              3       5
- *
- * Example:
- * Input List:
- *    Node values: 1 -> 2 -> 3 -> 4 -> 5
- *    Sibling relationships:
- *      - 1's sibling -> 3
- *      - 2's sibling -> 5
- *      - 5's sibling -> 2
- *
- * When copied, both lists will have the same structure and sibling connections.
+ * Example 2:
+ * Input: values = [1], sibling = {}
+ * Output: [1] (copied node, not the same address)
  */
 
 #include "list.h"

src/4_Lists/delete_duplicates.cpp

@@ -1,29 +1,23 @@
 /*
  * Task: Delete duplicate values from a singly linked list.
  *
- * DELETE DUPLICATE NODES IN A LINKED LIST
+ * REMOVE DUPLICATES FROM AN UNSORTED LINKED LIST
  *
- * Define a class named UniqueList that extends a basic singly linked list
- * (from list.h) and provides an operation to delete duplicate nodes from the
- * list. The deletion process is implemented by traversing the list and using
- * an unordered_set to keep track of seen values. When a duplicate node is
- * encountered, it is removed from the list.
+ * Problem:
+ * Given the head of an unsorted singly linked list, remove duplicate values so
+ * that each value appears only once. Keep the first occurrence of each value.
  *
- * ASCII Illustration:
+ * Constraints:
+ * - 0 <= n <= 10^5
+ * - Node values are 32-bit signed integers.
  *
- *      Before: 1 -> 2 -> 3 -> 4 -> 4 -> 5
- *                      |         |
- *                      +---------+
+ * Example 1:
+ * Input: head = [1,2,3,4,4,5]
+ * Output: [1,2,3,4,5]
  *
- *      After:  1 -> 2 -> 3 -> 4 -> 5
- *
- * Example Input/Output:
- * Input List: 1, 2, 3, 4, 4, 5
- * Output List: 1, 2, 3, 4, 5
- *
- * Explanation:
- * The duplicate node containing 4 is removed so that each value appears only
- * once.
+ * Example 2:
+ * Input: head = [1,1,1,1,2]
+ * Output: [1,2]
  */
 
 #include "list.h"

src/4_Lists/delete_node.cpp

@@ -1,25 +1,24 @@
 /*
  * Task: Remove the first occurrence of a value from a singly linked list.
  *
- * REMOVE ELEMENT FROM A LINKED LIST
+ * REMOVE LINKED LIST ELEMENT
  *
- * Extend a basic singly linked list (as defined in list.h) by providing a
- * function to remove the first occurrence of a given value from the list.
+ * Problem:
+ * Given the head of a singly linked list and an integer target, remove the
+ * first node whose value equals target. If target does not exist, keep the
+ * list unchanged.
  *
- * ASCII Illustration:
+ * Constraints:
+ * - 0 <= n <= 10^5
+ * - Node values and target are 32-bit signed integers.
  *
- *     Before removal: 1 -> 2 -> 3 -> 4 -> 5
- *                     remove(3)
- *     After removal:  1 -> 2 -> 4 -> 5
+ * Example 1:
+ * Input: head = [1,2,3,4,5], target = 3
+ * Output: [1,2,4,5]
  *
- * Example:
- * Input:  List = [1, 2, 3, 4, 5], remove(3)
- * Output: List = [1, 2, 4, 5]
- *
- * Edge Cases:
- * - Removing the head element.
- * - Removing the tail element.
- * - Removing from a list with a single element.
+ * Example 2:
+ * Input: head = [1], target = 1
+ * Output: []
  */
 
 #include "list.h"

src/4_Lists/kth_node.cpp

@@ -1,25 +1,24 @@
 /*
  * Task: Find the kth element from the tail of a singly linked list.
  *
- * FIND KTH TO TAIL ELEMENT IN A LINKED LIST
+ * KTH NODE FROM END OF LIST
  *
- * Find the kth element from the tail (0-indexed) of a singly linked list.
- * Three solutions are provided:
+ * Problem:
+ * Given the head of a singly linked list and an integer k (0-indexed from the
+ * tail), return the value of the kth node from the end of the list.
  *
- * ASCII Illustration:
+ * Constraints:
+ * - 1 <= n <= 10^5
+ * - 0 <= k < n
+ * - Node values are 32-bit signed integers.
  *
- *      Linked List: 1 -> 2 -> 3 -> 4 -> 5
+ * Example 1:
+ * Input: head = [1,2,3,4,5], k = 0
+ * Output: 5
  *
- *      For k = 0 (0th from tail), the answer is 5.
- *      For k = 4 (4th from tail), the answer is 1.
- *
- * Example Input/Output:
- * Input:  List = 1 -> 2 -> 3 -> 4 -> 5, k = 1
+ * Example 2:
+ * Input: head = [1,2,3,4,5], k = 1
  * Output: 4
- *
- * Explanation:
- * For k=1, the kth element from the tail is the second-to-last element in the
- * list.
  */
 
 #include "list.h"

src/4_Lists/loops.cpp

@@ -1,30 +1,25 @@
 /*
  * Task: Detect whether a linked list contains a loop.
  *
- * DETECT LOOP IN A LINKED LIST (WITH LOOPS)
+ * LINKED LIST CYCLE
  *
- * Define a linked list class (ListWithLoops) that supports creating loops in
- * the list by connecting nodes arbitrarily. Memory management is handled by
- * storing all allocated nodes in a vector so that they can be safely deleted
- * even if a loop exists.
+ * Problem:
+ * Given the head of a linked list, determine whether it contains a cycle. A
+ * cycle exists if some node can be reached again by continuously following
+ * next pointers.
  *
- * ASCII Illustration:
+ * Constraints:
+ * - 0 <= n <= 10^5
+ * - Node values are 32-bit signed integers.
+ * - `next` may point to any node in the list or null.
  *
- *      Without Loop:
- *        1 -> nullptr
+ * Example 1:
+ * Input: head = [1,2,3,4,5], tail connects to index 2
+ * Output: true
  *
- *      With Loop:
- *        1 -> 2 -> 3 -> 4 -> 5
- *                 ^         |
- *                 |_________|
- *
- * Example:
- * Input:  List = [1, 2, 3, 4, 5] with connection from node 5 to node 3.
- * Output: hasLoop() returns true.
- *
- * Edge Cases:
- *  - A single node with no loop.
- *  - A node connected to itself.
+ * Example 2:
+ * Input: head = [1], tail connects to null
+ * Output: false
  */
 
 #include <algorithm>

src/4_Lists/merge.cpp

@@ -1,22 +1,24 @@
 /*
  * Task: Merge two sorted linked lists into one sorted list.
  *
- * MERGE TWO SORTED LINKED LISTS
+ * MERGE TWO SORTED LISTS
  *
- * ASCII Illustration:
+ * Problem:
+ * Given the heads of two sorted linked lists, merge them into one sorted list
+ * containing all nodes from both lists.
  *
- *    List1: 1 -> 3 -> 5
- *    List2: 2 -> 4 -> 6
+ * Constraints:
+ * - 0 <= n, m <= 10^5
+ * - -10^9 <= Node.val <= 10^9
+ * - Both input lists are sorted in non-decreasing order.
  *
- *    Merged: 1 -> 2 -> 3 -> 4 -> 5 -> 6
+ * Example 1:
+ * Input: list1 = [1,3,5], list2 = [2,4,6]
+ * Output: [1,2,3,4,5,6]
  *
- * Example:
- * Input:  list1 = [1, 3, 5], list2 = [2, 4, 6]
- * Output: [1, 2, 3, 4, 5, 6]
- *
- * Edge Cases:
- * - One or both lists are empty.
- * - Lists of different lengths.
+ * Example 2:
+ * Input: list1 = [1,2,3], list2 = []
+ * Output: [1,2,3]
  */
 
 #include "list.h"

src/4_Lists/print_reversely.cpp

@@ -1,32 +1,23 @@
 /*
  * Task: Print the elements of a linked list in reverse order.
  *
- * PRINT LINKED LIST IN REVERSE ORDER
+ * PRINT LINKED LIST IN REVERSE
  *
- * Demonstrate two approaches to print the elements of a linked list in reverse
- * order.
+ * Problem:
+ * Given the head of a singly linked list, output the node values from tail to
+ * head. This file demonstrates both iterative (stack) and recursive solutions.
  *
- * ASCII Illustration:
+ * Constraints:
+ * - 0 <= n <= 10^5
+ * - Node values are 32-bit signed integers.
  *
- *     List: 1 -> 2 -> 3
+ * Example 1:
+ * Input: head = [1,2,3]
+ * Output: [3,2,1]
  *
- *     Reverse Output:
- *         3
- *         2
- *         1
- *
- * Example:
- * Input:  List = [1, 2, 3]
- * Output:
- *         (Iterative)
- *             3
- *             2
- *             1
- *
- *         (Recursive)
- *             3
- *             2
- *             1
+ * Example 2:
+ * Input: head = []
+ * Output: []
  */
 
 #include "list.h"

src/4_Lists/reverse_list.cpp

@@ -1,28 +1,23 @@
 /*
  * Task: Reverse a singly linked list in-place using pointer re-linking.
  *
- * REVERSE A LINKED LIST USING UNIQUE_PTR
+ * REVERSE LINKED LIST
  *
- * Define a class ListWithReversion that extends a basic singly linked list
- * (from list.h) by providing a function to reverse the list. The reversal is
- * done by re-linking the nodes, which are managed by std::unique_ptr, without
- * creating new nodes.
+ * Problem:
+ * Given the head of a singly linked list, reverse the list in-place and return
+ * the reversed list.
  *
- * ASCII Illustration:
+ * Constraints:
+ * - 0 <= n <= 10^5
+ * - Node values are 32-bit signed integers.
  *
- *   Original List: 1 -> 2 -> 3 -> 4 -> 5
- *         |
- *       Reverse
- *         V
- *   Reversed List: 5 -> 4 -> 3 -> 2 -> 1
+ * Example 1:
+ * Input: head = [1,2,3,4,5]
+ * Output: [5,4,3,2,1]
  *
- * Example:
- * Input:  List = [1, 2, 3, 4, 5]
- * Output: List = [5, 4, 3, 2, 1]
- *
- * Edge Cases:
- * - An empty list remains empty.
- * - A list with a single element remains unchanged.
+ * Example 2:
+ * Input: head = []
+ * Output: []
  */
 
 #include "list.h"

src/4_Lists/sort.cpp

@@ -1,3 +1,25 @@
+/*
+ * Task: Sort a singly linked list in non-decreasing order.
+ *
+ * SORT LINKED LIST (INSERTION SORT)
+ *
+ * Problem:
+ * Given the head of a singly linked list, sort the list in ascending order.
+ * This implementation performs insertion sort by re-linking nodes.
+ *
+ * Constraints:
+ * - 0 <= n <= 10^5
+ * - -10^9 <= Node.val <= 10^9
+ *
+ * Example 1:
+ * Input: head = [2,4,5,1,3]
+ * Output: [1,2,3,4,5]
+ *
+ * Example 2:
+ * Input: head = [5,4,3,2,1]
+ * Output: [1,2,3,4,5]
+ */
+
 #include "list.h"
 #include <iostream>
 #include <memory>