Add some comments and TODOs

Vector.h

@@ -7,6 +7,8 @@ template <class T>
 class Vector {
   public:
     // Constructor
+    // If the needed capacity is known, it can be passed; other wise, a default
+    // capacity is reserved.
     Vector(unsigned int capacity = 10)
         : capacity(capacity), element_count(0), data(new T[capacity]) {
     }
@@ -28,7 +30,7 @@ class Vector {
 
     // Copy Assignment Operator using the copy-and-swap-idiom
     // Since this takes a value rather than a const reference due to
-    // copy-and-swap, this is also the Move Assignment Operator
+    // copy-and-swap, this is also the Move Assignment Operator.
     // This works because we pass-by-value, causing the copy constructor (which
     // does the actual copying) to be called, and then we swap the resulting
     // temporary into `this`.
@@ -43,12 +45,13 @@ class Vector {
         delete[] data;
     }
 
-    // Bracket Operator
+    // Bracket Operator for accessing elements
     T &operator[](unsigned int position) const {
         return at(position);
     }
 
-    // Equals Operator
+    // Equals Operator: Returns true if the number of elements is identical and
+    // each of these elements are equal
     bool operator==(const Vector &other) {
         if (size() != other.size()) return false;
 
@@ -75,9 +78,7 @@ class Vector {
     }
 
     void push_back(const T &element) {
-        if (element_count >= capacity) {
-            // TODO: Increase capacity!
-        }
+        // TODO: Allocate additional space if needed
 
         // Use placement new to directly use pre-allocated memory
         new (data + element_count) T(element);
@@ -87,28 +88,40 @@ class Vector {
     void erase(unsigned int position) {
         assert(position < element_count);
 
+        // Call the destructor on the given element
+        data[position].~T();
+
+        // Copy the other elements forwards
         std::copy_backward(data + position + 1, data + element_count,
                            data + element_count - 1);
 
         element_count--;
+
+        // TODO: Consider deallocating memory if a certain threshold was reached
     }
 
+    // Returns the number of elements in the vector, regardless of the actually
+    // reserved memory.
     unsigned int size() const {
         return element_count;
     }
 
+    // Returns the number of elements which could be in the vector using the
+    // currently allocated memory, regardless of how many of these slots are
+    // currently actually used.
     unsigned int length() const {
         return capacity;
     }
 
+    // Returns a reference to the element at the given position
     T &at(unsigned int position) const {
         assert(position < element_count);
         return data[position];
     }
 
-    // Expand the capacity (length) of the vector by the given addition
+    // Expand the capacity of the vector by the given addition
     void reserve(unsigned int addition) {
-        // TODO: Actual reserve
+        // TODO: Actual memory allocation
         capacity += addition;
     }
 
@@ -116,17 +129,20 @@ class Vector {
     // If this decreases the size, some elements are deleted
     // If this increases the size, some default-constructed elements are added
     void resize(unsigned int new_size) {
-        // TODO: Reserve if needed
         int difference = new_size - size();
 
         if (difference > 0) {
+            // TODO: Reserve more space if needed
+            // Add additional default-constructed items
             for (int i = 0; i < difference; i++) {
                 data[element_count + i] = T();
             }
         } else if (difference < 0) {
+            // Call the destructor on all excess items
             for (int i = -1; i > difference; i--) {
                 data[element_count + i].~T();
             }
+            // TODO: Consider deallocating space
         }
 
         element_count += difference;

test.cpp

@@ -160,7 +160,7 @@ SCENARIO("Move Assignment", "[vector]") {
 }
 
 SCENARIO("Reserve additional space", "[vector]") {
-    GIVEN("A vector with a given capacity") {
+    GIVEN("A vector with a given length") {
         Vector<int> v(5);
 
         REQUIRE(v.length() == 5);
@@ -168,7 +168,7 @@ SCENARIO("Reserve additional space", "[vector]") {
         WHEN("Reserving additional space") {
             v.reserve(10);
 
-            THEN("The capacity has increased accordingly") {
+            THEN("The length has increased accordingly") {
                 REQUIRE(v.length() == 15);
             }
         }