Documentation & Cocos2d-x C++ Style

cocos2dx/cocoa/CCAutoreleasePool.cpp

@@ -28,31 +28,31 @@ NS_CC_BEGIN
 
 static PoolManager* s_pPoolManager = NULL;
 
-AutoreleasePool::AutoreleasePool(void)
+AutoreleasePool::AutoreleasePool()
 {
     _managedObjectArray = new Array();
     _managedObjectArray->init();
 }
 
-AutoreleasePool::~AutoreleasePool(void)
+AutoreleasePool::~AutoreleasePool()
 {
     CC_SAFE_DELETE(_managedObjectArray);
 }
 
-void AutoreleasePool::addObject(Object* pObject)
+void AutoreleasePool::addObject(Object* object)
 {
-    _managedObjectArray->addObject(pObject);
+    _managedObjectArray->addObject(object);
 
-    CCASSERT(pObject->_reference > 1, "reference count should be greater than 1");
-    ++(pObject->_autoReleaseCount);
-    pObject->release(); // no ref count, in this case autorelease pool added.
+    CCASSERT(object->_reference > 1, "reference count should be greater than 1");
+    ++(object->_autoReleaseCount);
+    object->release(); // no ref count, in this case autorelease pool added.
 }
 
-void AutoreleasePool::removeObject(Object* pObject)
+void AutoreleasePool::removeObject(Object* object)
 {
-    for (unsigned int i = 0; i < pObject->_autoReleaseCount; ++i)
+    for (unsigned int i = 0; i < object->_autoReleaseCount; ++i)
     {
-        _managedObjectArray->removeObject(pObject, false);
+        _managedObjectArray->removeObject(object, false);
     }
 }
 
@@ -113,14 +113,13 @@ PoolManager::PoolManager()
 
 PoolManager::~PoolManager()
 {
-    
-     finalize();
+    finalize();
  
      // we only release the last autorelease pool here 
     _curReleasePool = 0;
-     _releasePoolStack->removeObjectAtIndex(0);
+    _releasePoolStack->removeObjectAtIndex(0);
  
-     CC_SAFE_DELETE(_releasePoolStack);
+    CC_SAFE_DELETE(_releasePoolStack);
 }
 
 void PoolManager::finalize()
@@ -156,12 +155,12 @@ void PoolManager::pop()
         return;
     }
 
-     int nCount = _releasePoolStack->count();
+    int nCount = _releasePoolStack->count();
 
     _curReleasePool->clear();
  
-      if(nCount > 1)
-      {
+    if (nCount > 1)
+    {
         _releasePoolStack->removeObjectAtIndex(nCount-1);
 
 //         if(nCount > 1)
@@ -175,16 +174,16 @@ void PoolManager::pop()
     /*_curReleasePool = NULL;*/
 }
 
-void PoolManager::removeObject(Object* pObject)
+void PoolManager::removeObject(Object* object)
 {
     CCASSERT(_curReleasePool, "current auto release pool should not be null");
 
-    _curReleasePool->removeObject(pObject);
+    _curReleasePool->removeObject(object);
 }
 
-void PoolManager::addObject(Object* pObject)
+void PoolManager::addObject(Object* object)
 {
-    getCurReleasePool()->addObject(pObject);
+    getCurReleasePool()->addObject(object);
 }
 
 

cocos2dx/cocoa/CCAutoreleasePool.h

@@ -36,36 +36,98 @@ NS_CC_BEGIN
 
 class CC_DLL AutoreleasePool : public Object
 {
-    Array*    _managedObjectArray;    
+    /**
+     * The underlying array of object managed by the pool.
+     *
+     * Although Array retains the object once when an object is added, proper
+     * Object::release() is called outside the array to make sure that the pool
+     * does not affect the managed object's reference count. So an object can
+     * be destructed properly by calling Object::release() even if the object
+     * is in the pool.
+     */
+    Array   *_managedObjectArray;
 public:
-    AutoreleasePool(void);
-    ~AutoreleasePool(void);
+    AutoreleasePool();
+    ~AutoreleasePool();
 
-    void addObject(Object *pObject);
-    void removeObject(Object *pObject);
+    /**
+     * Add a given object to this pool.
+     *
+     * The same object may be added several times to the same pool; When the
+     * pool is destructed, the object's Object::release() method will be called
+     * for each time it was added.
+     *
+     * @param object    The object to add to the pool.
+     */
+    void addObject(Object *object);
 
+    /**
+     * Remove a given object from this pool.
+     *
+     * @param object    The object to be removed from the pool.
+     */
+    void removeObject(Object *object);
+
+    /**
+     * Clear the autorelease pool.
+     *
+     * Object::release() will be called for each time the managed object is
+     * added to the pool.
+     */
     void clear();
 };
 
 class CC_DLL PoolManager
 {
-    Array*    _releasePoolStack;    
-    AutoreleasePool*                    _curReleasePool;
+    Array           *_releasePoolStack;
+    AutoreleasePool *_curReleasePool;
 
-    AutoreleasePool* getCurReleasePool();
+    AutoreleasePool *getCurReleasePool();
 public:
-    PoolManager();
-    ~PoolManager();
-    void finalize();
-    void push();
-    void pop();
-
-    void removeObject(Object* pObject);
-    void addObject(Object* pObject);
-
     static PoolManager* sharedPoolManager();
     static void purgePoolManager();
 
+    PoolManager();
+    ~PoolManager();
+
+    /**
+     * Clear all the AutoreleasePool on the pool stack.
+     */
+    void finalize();
+
+    /**
+     * Push a new AutoreleasePool to the pool stack.
+     */
+    void push();
+
+    /**
+     * Pop one AutoreleasePool from the pool stack.
+     *
+     * This method will ensure that there is at least one AutoreleasePool on
+     * the stack.
+     *
+     * The AutoreleasePool being poped is destructed.
+     */
+    void pop();
+
+    /**
+     * Remove a given object from the current autorelease pool.
+     *
+     * @param object    The object to be removed.
+     *
+     * @see AutoreleasePool::removeObject
+     */
+    void removeObject(Object *object);
+
+    /**
+     * Add a given object to the current autorelease pool.
+     *
+     * @param object    The object to add.
+     *
+     * @see AutoreleasePool::addObject
+     */
+    void addObject(Object *object);
+
     friend class AutoreleasePool;
 };
 

cocos2dx/cocoa/CCObject.cpp

@@ -30,7 +30,7 @@ THE SOFTWARE.
 
 NS_CC_BEGIN
 
-Object::Object(void)
+Object::Object()
 : _luaID(0)
 , _reference(1) // when the object is created, the reference count of it is 1
 , _autoReleaseCount(0)
@@ -40,7 +40,7 @@ Object::Object(void)
     _ID = ++uObjectCount;
 }
 
-Object::~Object(void)
+Object::~Object()
 {
     // if the object is managed, we should remove it
     // from pool manager
@@ -64,7 +64,7 @@ Object::~Object(void)
     }
 }
 
-void Object::release(void)
+void Object::release()
 {
     CCASSERT(_reference > 0, "reference count should greater than 0");
     --_reference;
@@ -75,32 +75,32 @@ void Object::release(void)
     }
 }
 
-void Object::retain(void)
+void Object::retain()
 {
     CCASSERT(_reference > 0, "reference count should greater than 0");
 
     ++_reference;
 }
 
-Object* Object::autorelease(void)
+Object* Object::autorelease()
 {
     PoolManager::sharedPoolManager()->addObject(this);
     return this;
 }
 
-bool Object::isSingleReference(void) const
+bool Object::isSingleReference() const
 {
     return _reference == 1;
 }
 
-unsigned int Object::retainCount(void) const
+unsigned int Object::retainCount() const
 {
     return _reference;
 }
 
-bool Object::isEqual(const Object *pObject)
+bool Object::isEqual(const Object *object)
 {
-    return this == pObject;
+    return this == object;
 }
 
 void Object::acceptVisitor(DataVisitor &visitor)

cocos2dx/cocoa/CCObject.h

@@ -64,25 +64,85 @@ public:
 class CC_DLL Object
 {
 public:
-    // object id, ScriptSupport need public _ID
+    /// object id, ScriptSupport need public _ID
     unsigned int        _ID;
-    // Lua reference id
+    /// Lua reference id
     int                 _luaID;
 protected:
-    // count of references
+    /// count of references
     unsigned int        _reference;
-    // count of autorelease
+    /// count of autorelease
     unsigned int        _autoReleaseCount;
 public:
-    Object(void);
-    virtual ~Object(void);
+    /**
+     * Constructor
+     *
+     * The object's reference count is 1 after construction.
+     */
+    Object();
+
+    virtual ~Object();
     
-    void release(void);
-    void retain(void);
-    Object* autorelease(void);
-    bool isSingleReference(void) const;
-    unsigned int retainCount(void) const;
-    virtual bool isEqual(const Object* pObject);
+    /**
+     * Release the ownership immediately.
+     *
+     * This decrements the object's reference count.
+     *
+     * If the reference count reaches 0 after the descrement, this object is
+     * destructed.
+     *
+     * @see retain, autorelease
+     */
+    void release();
+
+    /**
+     * Retains the ownership.
+     *
+     * This increases the object's reference count.
+     *
+     * @see release, autorelease
+     */
+    void retain();
+
+    /**
+     * Release the ownership sometime soon automatically.
+     *
+     * This descrements the object's reference count at the end of current
+     * autorelease pool block.
+     *
+     * If the reference count reaches 0 after the descrement, this object is
+     * destructed.
+     *
+     * @returns The object itself.
+     *
+     * @see AutoreleasePool, retain, release
+     */
+    Object* autorelease();
+
+    /**
+     * Returns a boolean value that indicates whether there is only one
+     * reference to the object. That is, whether the reference count is 1.
+     *
+     * @returns Whether the object's reference count is 1.
+     */
+    bool isSingleReference() const;
+
+    /**
+     * Returns the object's current reference count.
+     *
+     * @returns The object's reference count.
+     */
+    unsigned int retainCount() const;
+
+    /**
+     * Returns a boolean value that indicates whether this object and a given
+     * object are equal.
+     *
+     * @param object    The object to be compared to this object.
+     *
+     * @returns True if this object and @p object are equal, otherwise false.
+     */
+    virtual bool isEqual(const Object* object);
 
     virtual void acceptVisitor(DataVisitor &visitor);