Merge pull request #4476 from dumganhar/iss2790-container-comments

issue #2790: Updates comments for Map<K, V> and Vector<T> container.

cocos/base/CCMap.h

@@ -59,12 +59,14 @@ public:
     const_iterator cbegin() const { return _data.cbegin(); }
     const_iterator cend() const { return _data.cend(); }
     
+    /** Default constructor */
     Map<K, V>()
     : _data()
     {
         CCLOGINFO("In the default constructor of Map!");
     }
     
+    /** Contructor with capacity */
     explicit Map<K, V>(int capacity)
     : _data()
     {
@@ -72,6 +74,7 @@ public:
         _data.reserve(capacity);
     }
 
+    /** Copy constructor */
     Map<K, V>(const Map<K, V>& other)
     {
         CCLOGINFO("In the copy constructor of Map!");
@@ -79,40 +82,50 @@ public:
         addRefForAllObjects();
     }
     
+    /** Move constructor */
     Map<K, V>(Map<K, V>&& other)
     {
         CCLOGINFO("In the move constructor of Map!");
         _data = std::move(other._data);
     }
     
+    /** Destructor 
+     *  It will release all objects in map.
+     */
     ~Map<K, V>()
     {
         CCLOGINFO("In the destructor of Map!");
         clear();
     }
 
-    /** Sets capacity of current array */
+    /** Sets capacity of the map */
     void reserve(int capacity)
     {
         _data.reserve(capacity);
     }
     
-    /** Returns capacity of the array */
+    /** Returns capacity of the map */
     size_t capacity() const
     {
         return _data.capacity();
     }
     
+    /** The number of elements in the map. */
     size_t size() const
     {
         return _data.size();
     }
 
+    /** Returns a bool value indicating whether the map container is empty, i.e. whether its size is 0.
+     *  @note This function does not modify the content of the container in any way.
+     *        To clear the content of an array object, member function unordered_map::clear exists.
+     */
     bool empty() const
     {
         return _data.empty();
     }
     
+    /** Returns all keys in the map */
     std::vector<K> keys() const
     {
         std::vector<K> keys;
@@ -127,6 +140,7 @@ public:
         return keys;
     }
 
+    /** Returns all keys that matches the object */
     std::vector<K> keys(V object) const
     {
         std::vector<K> keys;
@@ -142,6 +156,11 @@ public:
         return keys;
     }
 
+    /** @brief Returns a reference to the mapped value of the element with key k in the map.
+     *  @note If key does not match the key of any element in the container, the function return nullptr.
+     *  @param key Key value of the element whose mapped value is accessed.
+     *       Member type K is the keys for the elements in the container. defined in Map<K, V> as an alias of its first template parameter (Key).
+     */
     const V at(const K& key) const
     {
         auto iter = _data.find(key);
@@ -158,6 +177,13 @@ public:
         return nullptr;
     }
     
+    /** @brief Searches the container for an element with 'key' as key and returns an iterator to it if found,
+     *         otherwise it returns an iterator to Map<K, V>::end (the element past the end of the container).
+     *  @param key Key to be searched for.
+     *         Member type 'K' is the type of the keys for the elements in the container,
+     *         defined in Map<K, V> as an alias of its first template parameter (Key).
+     *
+     */
     const_iterator find(const K& key) const
     {
         return _data.find(key);
@@ -168,6 +194,11 @@ public:
         return _data.find(key);
     }
     
+    /** @brief Inserts new elements in the map.
+     *  @note If the container has already contained the key, this function will erase the old pair(key, object)  and insert the new pair.
+     *  @param key The key to be inserted.
+     *  @param object The object to be inserted.
+     */
     void insert(const K& key, V object)
     {
         CCASSERT(object != nullptr, "Object is nullptr!");
@@ -176,11 +207,22 @@ public:
         object->retain();
     }
 
+    /** @brief Removes an element with an iterator from the Map<K, V> container.
+     *  @param position Iterator pointing to a single element to be removed from the Map<K, V>.
+     *         Member type const_iterator is a forward iterator type.
+     */
     iterator erase(const_iterator position)
     {
+        CCASSERT(position >= _data.begin() && position < _data.end(), "");
+        position->second->release();
         return _data.erase(position);
     }
     
+    /** @brief Removes an element with an iterator from the Map<K, V> container.
+     *  @param k Key of the element to be erased.
+     *         Member type 'K' is the type of the keys for the elements in the container,
+     *         defined in Map<K, V> as an alias of its first template parameter (Key).
+     */
     size_t erase(const K& k)
     {
         auto iter = _data.find(k);
@@ -194,6 +236,9 @@ public:
         return 0;
     }
     
+    /** @brief Removes some elements with a vector which contains keys in the map.
+     *  @param keys Keys of elements to be erased.
+     */
     void erase(const std::vector<K>& keys)
     {
         std::for_each(keys.cbegin(), keys.cend(), [this](const K& key){
@@ -201,6 +246,10 @@ public:
         });
     }
     
+    /** All the elements in the Map<K,V> container are dropped:
+     *  their reference count will be decreased, and they are removed from the container,
+     *  leaving it with a size of 0.
+     */
     void clear()
     {
         for (auto iter = _data.cbegin(); iter != _data.cend(); ++iter)
@@ -211,6 +260,9 @@ public:
         _data.clear();
     }
     
+    /** @brief Gets a random object in the map
+     *  @return Returns the random object if the map isn't empty, otherwise it returns nullptr.
+     */
     V getRandomObject() const
     {
         if (!_data.empty())
@@ -246,6 +298,7 @@ public:
 //        return _data.at(key);
 //    }
     
+    /** Copy assignment operator */
     Map<K, V>& operator= ( const Map<K, V>& other )
     {
         CCLOGINFO("In the copy assignment operator of Map!");
@@ -255,6 +308,7 @@ public:
         return *this;
     }
 
+    /** Move assignment operator */
     Map<K, V>& operator= ( Map<K, V>&& other )
     {
         CCLOGINFO("In the move assignment operator of Map!");
@@ -264,6 +318,7 @@ public:
     
 protected:
     
+    /** Retains all the objects in the map */
     void addRefForAllObjects()
     {
         for (auto iter = _data.begin(); iter != _data.end(); ++iter)

cocos/base/CCVector.h

@@ -71,7 +71,7 @@ public:
         
     }
     
-    /** creates an emptry Vector */
+    /** Constructor with a capacity */
     explicit Vector<T>(int capacity)
     : _data()
     {
@@ -79,12 +79,14 @@ public:
         reserve(capacity);
     }
 
+    /** Destructor */
     ~Vector<T>()
     {
         CCLOGINFO("In the destructor of Vector.");
         clear();
     }
 
+    /** Copy constructor */
     Vector<T>(const Vector<T>& other)
     {
         CCLOGINFO("In the copy constructor!");
@@ -99,6 +101,7 @@ public:
         _data = std::move(other._data);
     }
     
+    /** Copy assignment operator */
     Vector<T>& operator=(const Vector<T>& other)
     {
         CCLOGINFO("In the copy assignment operator!");
@@ -108,6 +111,7 @@ public:
         return *this;
     }
     
+    /** Move assignment operator */
     Vector<T>& operator=(Vector<T>&& other)
     {
         CCLOGINFO("In the move assignment operator!");
@@ -126,31 +130,49 @@ public:
 //        return _data[index];
 //    }
     
-    /** Sets capacity of current array */
+    /** @brief Request a change in capacity 
-    void reserve(int capacity)
+     *  @param capacity Minimum capacity for the vector.
+     *         If n is greater than the current vector capacity, 
+     *         the function causes the container to reallocate its storage increasing its capacity to n (or greater).
+     */
+    void reserve(int n)
     {
-        _data.reserve(capacity);
+        _data.reserve(n);
     }
     
-    /** Returns capacity of the array */
+    /** @brief Returns the size of the storage space currently allocated for the vector, expressed in terms of elements.
+     *  @note This capacity is not necessarily equal to the vector size. 
+     *        It can be equal or greater, with the extra space allowing to accommodate for growth without the need to reallocate on each insertion.
+     *  @return The size of the currently allocated storage capacity in the vector, measured in terms of the number elements it can hold.
+     */
     int capacity() const
     {
         return _data.capacity();
     }
     
-    // Querying an Array
+    /** @brief Returns the number of elements in the vector.
-
+     *  @note This is the number of actual objects held in the vector, which is not necessarily equal to its storage capacity.
-    /** Returns element count of the array */
+     *  @return The number of elements in the container.
+     */
     int size() const
     {
         return  static_cast<int>(_data.size());
     }
     
+    /** @brief Returns whether the vector is empty (i.e. whether its size is 0).
+     *  @note This function does not modify the container in any way. To clear the content of a vector, see Vector<T>::clear.
+     */
     bool empty() const
     {
         return _data.empty();
     }
     
+    /** Returns the maximum number of elements that the vector can hold. */
+    size_t max_size() const
+    {
+        return _data.max_size();
+    }
+    
     /** Returns index of a certain object, return UINT_MAX if doesn't contain the object */
     int getIndex(T object) const
     {
@@ -161,6 +183,10 @@ public:
         return -1;
     }
 
+    /** @brief Find the object in the vector.
+     *  @return Returns an iterator to the first element in the range [first,last) that compares equal to val. 
+     *          If no such element is found, the function returns last.
+     */
     const_iterator find(T object) const
     {
         return std::find(_data.begin(), _data.end(), object);
@@ -171,25 +197,26 @@ public:
         return std::find(_data.begin(), _data.end(), object);
     }
     
-    /** Returns an element with a certain index */
+    /** Returns the element at position 'index' in the vector. */
     T at(int index) const
     {
         CCASSERT( index >= 0 && index < size(), "index out of range in getObjectAtIndex()");
         return _data[index];
     }
 
+    /** Returns the first element in the vector. */
     T front() const
     {
         return _data.front();
     }
     
-    /** Returns the last element of the array */
+    /** Returns the last element of the vector. */
     T back() const
     {
         return _data.back();
     }
 
-    /** Returns a random element */
+    /** Returns a random element of the vector. */
     T getRandomObject() const
     {
         if (!_data.empty())
@@ -200,13 +227,13 @@ public:
         return nullptr;
     }
 
-    /** Returns a Boolean value that indicates whether object is present in array. */
+    /** Returns a Boolean value that indicates whether object is present in vector. */
     bool contains(T object) const
     {
         return( std::find(_data.begin(), _data.end(), object) != _data.end() );
     }
 
-    /** returns true if the the arrays are equal */
+    /** Returns true if the two vectors are equal */
     bool equals(const Vector<T> &other)
     {
         size_t s = this->size();
@@ -223,9 +250,13 @@ public:
         return true;
     }
 
-    // Adding Objects
+    // Adds objects
     
-    /** Add a certain object */
+    /** @brief Adds a new element at the end of the vector, after its current last element.
+     *  @note This effectively increases the container size by one,
+     *        which causes an automatic reallocation of the allocated storage space 
+     *        if -and only if- the new vector size surpasses the current vector capacity.
+     */
     void pushBack(T object)
     {
         CCASSERT(object != nullptr, "The object should not be nullptr");
@@ -233,7 +264,7 @@ public:
         object->retain();
     }
     
-    /** Add all elements of an existing array */
+    /** Inserts all elements of an existing vector */
     void insert(const Vector<T>& other)
     {
         for( auto it = other.begin(); it != other.end(); ++it ) {
@@ -242,7 +273,12 @@ public:
         }
     }
 
-    /** Insert a certain object at a certain index */
+    /** @brief Insert a certain object at a certain index 
+     *  @note The vector is extended by inserting new elements before the element at the specified 'index',
+     *        effectively increasing the container size by the number of elements inserted.
+     *        This causes an automatic reallocation of the allocated storage space 
+     *        if -and only if- the new vector size surpasses the current vector capacity.
+     */
     void insert(int index, T object)
     {
         CCASSERT(index >= 0 && index <= size(), "Invalid index!");
@@ -251,9 +287,11 @@ public:
         object->retain();
     }
     
-    // Removing Objects
+    // Removes Objects
 
-    /** Remove last object */
+    /** Removes the last element in the vector, 
+     *  effectively reducing the container size by one, decrease the referece count of the deleted object.
+     */
     void popBack()
     {
         CCASSERT(!_data.empty(), "no objects added");
@@ -262,7 +300,10 @@ public:
         last->release();
     }
     
-    /** Remove a certain object */
+    /** @brief Remove a certain object.
+     *  @param object The object to be removed.
+     *  @param toRelease Whether to decrease the referece count of the deleted object.
+     */
     void erase(T object, bool toRelease = true)
     {
         CCASSERT(object != nullptr, "The object should not be nullptr");
@@ -273,7 +314,11 @@ public:
             object->release();
     }
 
-    /** Removes an element with a certain index */
+    /** @brief Removes from the vector with an iterator. 
+     *  @param position Iterator pointing to a single element to be removed from the vector.
+     *  @return An iterator pointing to the new location of the element that followed the last element erased by the function call.
+     *          This is the container end if the operation erased the last element in the sequence.
+     */
     iterator erase(iterator position)
     {
         CCASSERT(position >= _data.begin() && position < _data.end(), "Invalid position!");
@@ -281,6 +326,12 @@ public:
         return _data.erase(position);
     }
     
+    /** @brief Removes from the vector with a range of elements (  [first, last)  ).
+     *  @param first The beginning of the range
+     *  @param last The end of the range, the 'last' will not used, it's only for indicating the end of range.
+     *  @return An iterator pointing to the new location of the element that followed the last element erased by the function call.
+     *          This is the container end if the operation erased the last element in the sequence.
+     */
     iterator erase(const_iterator first, const_iterator last)
     {
         for (auto iter = first; iter != last; ++iter)
@@ -291,15 +342,22 @@ public:
         return _data.erase(first, last);
     }
     
-    void erase(int index)
+    /** @brief Removes from the vector with an index.
+     *  @param index The index of the element to be removed from the vector.
+     *  @return An iterator pointing to the new location of the element that followed the last element erased by the function call.
+     *          This is the container end if the operation erased the last element in the sequence.
+     */
+    iterator erase(int index)
     {
         CCASSERT(!_data.empty() && index >=0 && index < size(), "Invalid index!");
         auto it = std::next( begin(), index );
         (*it)->release();
-        _data.erase(it);
+        return _data.erase(it);
     }
 
-    /** Removes all objects */
+    /** @brief Removes all elements from the vector (which are destroyed), leaving the container with a size of 0.
+     *  @note All the elements in the vector will be released (referece count will be decreased).
+     */
     void clear()
     {
         for( auto it = std::begin(_data); it != std::end(_data); ++it ) {
@@ -340,18 +398,19 @@ public:
         object->retain();
     }
 
-    /** reverses the array */
+    /** reverses the vector */
     void reverse()
     {
         std::reverse( std::begin(_data), std::end(_data) );
     }
     
-    /** Shrinks the array so the memory footprint corresponds with the number of items */
+    /** Shrinks the vector so the memory footprint corresponds with the number of items */
     void shrinkToFit()
     {
         _data.shrink_to_fit();
     }
     
+    /** Traverses through the vector and applys the callback function for each element */
     void forEach(const std::function<void(T)>& callback)
     {
         if (empty())
@@ -362,6 +421,7 @@ public:
         });
     }
     
+    /** Traverses through the vector and applys the callback function for each element */
     void forEach(const std::function<void(T)>& callback) const
     {
         if (empty())
@@ -372,6 +432,7 @@ public:
         });
     }
   
+    /** Traverses through the vector in reversed order and applys the callback function for each element */
     void forEachReverse(const std::function<void(T)>& callback)
     {
         if (empty())
@@ -382,6 +443,7 @@ public:
         });
     }
     
+    /** Traverses through the vector in reversed order and applys the callback function for each element */
     void forEachReverse(const std::function<void(T)>& callback) const
     {
         if (empty())
@@ -392,6 +454,11 @@ public:
         });
     }
     
+    /** @brief Sorts all elements in the vector according the binary callback function.
+     *  @param callback Binary function that accepts two elements in the vector as arguments,
+     *         and returns a value convertible to bool. 
+     *         The value returned indicates whether the element passed as first argument is considered to go before the second in the specific strict weak ordering it defines.
+     */
     void sort(const std::function<bool(T, T)>& callback)
     {
         if (empty())
@@ -404,6 +471,7 @@ public:
     
 protected:
     
+    /** Retains all the objects in the vector */
     void addRefForAllObjects()
     {
         std::for_each(_data.begin(), _data.end(), [](T obj){