Add another option for c heapsort, minor refactors, update docs

c/data_structures/heap.c

@@ -1,6 +1,5 @@
 #include "heap.h"
 
-// TODO: remove the extra checks for heap_size if i don't need them based on calling
 static int parent(int i) {
     return (i > 0) ? (i - 1) / 2 : -1;
 }

c/data_structures/heap.h

@@ -1,23 +1,9 @@
 #pragma once
 
-typedef struct dlos_ComparableNode {
-    void *value;
-} dlos_ComparableNode;
-
-typedef struct dlos_Heap {
-    int size;
-    dlos_ComparableNode *arr;
-    int arr_size;
-    int (*compare)(dlos_ComparableNode *a, dlos_ComparableNode *b);
-} dlos_Heap;
-
-void dlos_node_swap(dlos_ComparableNode *arr, int a, int b);
-void dlos_sift_down(int i, dlos_Heap *h);
-void dlos_max_heap(dlos_Heap *h);
-
 // example of how the heap can be used
 // here, each node value points to a plain int, but can substitute with other types
 //
+// // define a comparison function, a > b returns -1, a == b returns 0, a < b returns 1
 // int compare_nodes(dlos_ComparableNode *a, dlos_ComparableNode *b) {
 //     int left = *((int*) a->value);
 //     int right = *((int*) b->value);
@@ -33,16 +19,22 @@ void dlos_max_heap(dlos_Heap *h);
 // int main(int argc, char *argv[]) {
 //     int test_size = 10;
 //     int data_storage[] = {73, 6, 57, 88, 60, 42, 83, 72, 48, 85};
+//
+//     // define an array of dlos_ComparableNode and fill it with the desired data
+//     // note: if using heap memory, just use for array, keep dlos_Heap in stack memory
 //     dlos_ComparableNode a[test_size];
 //     for (int i = 0; i < test_size; i++) {
 //         a[i].value = &data_storage[i];
 //     }
+//     // then define the dlos_Heap with the above array, compare function, and sizes
 //     dlos_Heap heap = {
 //         .size = test_size,
 //         .arr = a,
 //         .arr_size = test_size,
 //         .compare = compare_nodes
 //     };
+//
+//     // then can use the heap; for example: order data into a max heap and sort it
 //     dlos_max_heap(&heap);
 //     dlos_sort_heap(&heap);
 //     for (int i = 0; i < test_size; i++) {
@@ -52,3 +44,18 @@ void dlos_max_heap(dlos_Heap *h);
 //     }
 //     return 0;
 // }
+
+typedef struct dlos_ComparableNode {
+    void *value;
+} dlos_ComparableNode;
+
+typedef struct dlos_Heap {
+    int size;
+    dlos_ComparableNode *arr;
+    int arr_size;
+    int (*compare)(dlos_ComparableNode *a, dlos_ComparableNode *b);
+} dlos_Heap;
+
+void dlos_node_swap(dlos_ComparableNode *arr, int a, int b);
+void dlos_sift_down(int i, dlos_Heap *h);
+void dlos_max_heap(dlos_Heap *h);