Update README.md and Documentation.md

README.md

@@ -85,16 +85,14 @@ Check out the **Documentation.md** to know exactly what represents the *end* and
 
 When including `macro_collections.h` in your source code you gain access to a macro called `COLLECTION_GENERATE` with the following parameters:
 
-* \*__C__ - Container name in uppercase (*LIST*, *LINKEDLIST*, *STACK*, *QUEUE*, *DEQUE*, *HEAP*, *TREESET*, *TREEMAP*, *HASHSET*, *HASHMAP*).
-* \*__PFX__ - Functions prefix or namespace.
-* \*__SNAME__ - Structure name (`typedef struct SNAME##_s SNAME`).
+* __C__ - Container name in uppercase (*LIST*, *LINKEDLIST*, *STACK*, *QUEUE*, *DEQUE*, *HEAP*, *TREESET*, *TREEMAP*, *HASHSET*, *HASHMAP*).
+* __PFX__ - Functions prefix or namespace.
+* __SNAME__ - Structure name (`typedef struct SNAME##_s SNAME`).
 * __FMOD__ - Function modifier (`static` or empty).
-* \*\*__K__ - Key type. Only used in *HASHMAP* and *TREEMAP*; ignored by others.
-* \*__V__ - Value type. Primary type for most collections, or value to be mapped by *HASHMAP* and *TREEMAP*.
+* \*__K__ - Key type. Only used in *HASHMAP* and *TREEMAP*; ignored by others.
+* __V__ - Value type. Primary type for most collections, or value to be mapped by *HASHMAP* and *TREEMAP*.
 
-\* Required parameters
-
-\*\* Required only by *HASHMAP* and *TREEMAP*
+\* Required only by *HASHMAP* and *TREEMAP*
 
 **In fact, all macros follow this pattern.** So whenever you see a macro with a bunch of parameters and you don't know what they are, you can check out the above list.
 
@@ -105,4 +103,28 @@ When including `foreach.h` in your source code you gain access to all for-each m
 * __TARGET__ - The variable name of the collection you wish to iterate over.
 * __BODY__ - Block of code.
 
-Inside body you will have access to the iterator variable. With it you can use functions to access the key, value or index from the iterator.
+Inside body you will have access to the iterator variable. With it you can use functions to access the key, value or index from the iterator. Checkout the documentation for more details.
+
+## Design Decisions
+
+### Stack vs Heap Allocation
+
+Currently all collections need to be allocated on the heap. Iterators have both options but it is encouraged to allocate them on the stack since they don't require dynamic memory.
+
+### Some collections overlap others in terms of functionality
+
+Yes, you can use a Deque as a Queue or a List as a Stack without any major cost, but the idea is to have the least amount of code to fulfill the needs of a collection.
+
+Take for example the Stack. It is simple, small and doesn't have many functions. If you generate a List to be used (only) as a Stack (which is one of the bulkiest collections) you'll end up with a lot of code generated and compiled for nothing.
+
+The Deque versus Queue situation is a little less problematic, but again, you need to be careful when generating a lot of code as compilation times might go up to 15 seconds even with modern ultra-fast compilers.
+
+Another example is using a HashMap/TreeMap as a HashSet/TreeSet (with a dummy value that is never used), but I just think that this is a bad thing to do and you would be wasting some memory. Also, the sets generate a lot of code related to set theory, whereas maps don't.
+
+### But what about the LinkedList ?
+
+You can use them as Stacks, Queues and Deques, but with modern memory hierarchy models, array-based data structures have a significantly faster runtime due to caching, so I didn't bother to have specific implementations of those aforementioned collections.
+
+### You can't structurally modify a collection when iterating over it
+
+Modifying a collection will possibly invalidate all iterators currently initialized by it. Currently, the only collection that allows this is the LinkedList (using the node-based functions, not the iterator).