Merge pull request #3404 from timothyqiu/docfix

Documentation fix: broken links and wrong encoding in the doc...

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);
 

extensions/GUI/CCControlExtension/CCControl.h

@@ -164,7 +164,7 @@ public:
      *
      * @param touch A Touch object that represents a touch.
      *
-     * @return YES whether a touch is inside the receiver¡¯s rect.
+     * @return Whether a touch is inside the receiver's rect.
      */
     virtual bool isTouchInside(Touch * touch);
 
@@ -260,4 +260,4 @@ protected:
 
 NS_CC_EXT_END
 
-#endif
+#endif

extensions/GUI/CCControlExtension/CCControlSaturationBrightnessPicker.h

@@ -47,9 +47,9 @@ NS_CC_EXT_BEGIN
 
 class ControlSaturationBrightnessPicker : public Control
 {
-    /** Contains the receiver¡¯s current saturation value. */
+    /** Contains the receiver's current saturation value. */
     CC_SYNTHESIZE_READONLY(float, _saturation, Saturation);
-    /** Contains the receiver¡¯s current brightness value. */
+    /** Contains the receiver's current brightness value. */
     CC_SYNTHESIZE_READONLY(float, _brightness, Brightness);
 
     //not sure if these need to be there actually. I suppose someone might want to access the sprite?
@@ -88,4 +88,4 @@ protected:
 
 NS_CC_EXT_END
 
-#endif
+#endif

extensions/GUI/CCControlExtension/CCControlSlider.h

@@ -55,7 +55,7 @@ public:
      * Creates a slider with a given background sprite and a progress bar and a
      * thumb item.
      *
-     * @see initWithBackgroundSprite:progressSprite:thumbMenuItem:
+     * @see initWithSprites
      */
     static ControlSlider* create(Sprite * backgroundSprite, Sprite* pogressSprite, Sprite* thumbSprite);
 
@@ -94,7 +94,7 @@ protected:
     float valueForLocation(Point location);
 
     //maunally put in the setters
-    /** Contains the receiver¡¯s current value. */
+    /** Contains the receiver's current value. */
     CC_SYNTHESIZE_READONLY(float, _value, Value);
 
     /** Contains the minimum value of the receiver.

extensions/GUI/CCControlExtension/CCScale9Sprite.h

@@ -63,7 +63,7 @@ public:
      * Creates a 9-slice sprite with a texture file, a delimitation zone and
      * with the specified cap insets.
      *
-     * @see initWithFile:rect:centerRegion:
+     * @see initWithFile(const char *file, Rect rect, Rect capInsets)
      */
     static Scale9Sprite* create(const char* file, Rect rect,  Rect capInsets);
 
@@ -71,7 +71,7 @@ public:
      * Creates a 9-slice sprite with a texture file. The whole texture will be
      * broken down into a 3×3 grid of equal blocks.
      *
-     * @see initWithFile:capInsets:
+     * @see initWithFile(Rect capInsets, const char *file)
      */
     static Scale9Sprite* create(Rect capInsets, const char* file);
 
@@ -79,7 +79,7 @@ public:
      * Creates a 9-slice sprite with a texture file and a delimitation zone. The
      * texture will be broken down into a 3×3 grid of equal blocks.
      *
-     * @see initWithFile:rect:
+     * @see initWithFile(const char *file, Rect rect)
      */
     static Scale9Sprite* create(const char* file, Rect rect);
 
@@ -87,7 +87,7 @@ public:
      * Creates a 9-slice sprite with a texture file. The whole texture will be
      * broken down into a 3×3 grid of equal blocks.
      *
-     * @see initWithFile:
+     * @see initWithFile(const char *file)
      */
     static Scale9Sprite* create(const char* file);
 
@@ -97,7 +97,7 @@ public:
      * to resize the sprite will all it's 9-slice goodness intract.
      * It respects the anchorPoint too.
      *
-     * @see initWithSpriteFrame:
+     * @see initWithSpriteFrame(SpriteFrame *spriteFrame)
      */
     static Scale9Sprite* createWithSpriteFrame(SpriteFrame* spriteFrame);
 
@@ -107,7 +107,7 @@ public:
      * to resize the sprite will all it's 9-slice goodness intract.
      * It respects the anchorPoint too.
      *
-     * @see initWithSpriteFrame:centerRegion:
+     * @see initWithSpriteFrame(SpriteFrame *spriteFrame, Rect capInsets)
      */
     static Scale9Sprite* createWithSpriteFrame(SpriteFrame* spriteFrame, Rect capInsets);
 
@@ -117,7 +117,7 @@ public:
      * to resize the sprite will all it's 9-slice goodness intract.
      * It respects the anchorPoint too.
      *
-     * @see initWithSpriteFrameName:
+     * @see initWithSpriteFrameName(const char *spriteFrameName)
      */
     static Scale9Sprite* createWithSpriteFrameName(const char*spriteFrameName);
 
@@ -128,7 +128,7 @@ public:
      * to resize the sprite will all it's 9-slice goodness intract.
      * It respects the anchorPoint too.
      *
-     * @see initWithSpriteFrameName:centerRegion:
+     * @see initWithSpriteFrameName(const char *spriteFrameName, Rect capInsets)
      */
     static Scale9Sprite* createWithSpriteFrameName(const char*spriteFrameName, Rect capInsets);
 

extensions/GUI/CCScrollView/CCScrollView.h

@@ -48,7 +48,7 @@ public:
 
 
 /**
- * ScrollView support for cocos2d for iphone.
+ * ScrollView support for cocos2d-x.
  * It provides scroll view functionalities to cocos2d projects natively.
  */
 class ScrollView : public Layer

extensions/GUI/CCScrollView/CCTableView.h

@@ -124,10 +124,9 @@ public:
 
 
 /**
- * UITableView counterpart for cocos2d for iphone.
- *
- * this is a very basic, minimal implementation to bring UITableView-like component into cocos2d world.
+ * UITableView support for cocos2d-x.
  *
+ * This is a very basic, minimal implementation to bring UITableView-like component into cocos2d world.
  */
 class TableView : public ScrollView, public ScrollViewDelegate
 {