add comments.

cocos/base/CCEvent.h

@@ -33,12 +33,13 @@ NS_CC_BEGIN
 
 class Node;
 
-/**
+/** @class Event
- *   Base class of all kinds of events.
+ * @brief Base class of all kinds of events.
  */
 class CC_DLL Event : public Ref
 {
 public:
+    /** Type Event type.*/
     enum class Type
     {
         TOUCH,
@@ -54,21 +55,29 @@ CC_CONSTRUCTOR_ACCESS:
     /** Constructor */
     Event(Type type);
 public:
-    /** Destructor */
+    /** Destructor.
+     */
     virtual ~Event();
 
-    /** Gets the event type */
+    /** Gets the event type.
+     *
+     * @return The event type.
+     */
 	inline Type getType() const { return _type; };
     
-    /** Stops propagation for current event */
+    /** Stops propagation for current event.
+     */
     inline void stopPropagation() { _isStopped = true; };
     
-    /** Checks whether the event has been stopped */
+    /** Checks whether the event has been stopped.
+     *
+     * @return True if the event has been stopped.
+     */
     inline bool isStopped() const { return _isStopped; };
     
-    /** @brief Gets current target of the event
+    /** Gets current target of the event.
-     *  @return The target with which the event associates.
+     * @return The target with which the event associates.
-     *  @note It onlys be available when the event listener is associated with node. 
+     * @note It onlys be available when the event listener is associated with node.
      *        It returns 0 when the listener is associated with fixed priority.
      */
     inline Node* getCurrentTarget() { return _currentTarget; };

cocos/base/CCEventAcceleration.h

@@ -30,9 +30,16 @@
 
 NS_CC_BEGIN
 
+/** @class EventAcceleration
+ * @brief Accelerometer event.
+ */
 class CC_DLL EventAcceleration : public Event
 {
 public:
+    /** Constructor.
+     *
+     * @param acc A given Acceleration.
+     */
     EventAcceleration(const Acceleration& acc);
     
 private:

cocos/base/CCEventCustom.h

@@ -30,19 +30,34 @@
 
 NS_CC_BEGIN
 
+/** @class EventCustom
+ * @brief Custom event.
+ */
 class CC_DLL EventCustom : public Event
 {
 public:
-    /** Constructor */
+    /** Constructor.
+     *
+     * @param eventName A given name of the custom event.
+     */
     EventCustom(const std::string& eventName);
     
-    /** Sets user data */
+    /** Sets user data.
+     *
+     * @param data The user data pointer, it's a void*.
+     */
     inline void setUserData(void* data) { _userData = data; };
     
-    /** Gets user data */
+    /** Gets user data.
+     *
+     * @return The user data pointer, it's a void*.
+     */
     inline void* getUserData() const { return _userData; };
     
-    /** Gets event name */
+    /** Gets event name.
+     *
+     * @return The name of the event.
+     */
     inline const std::string& getEventName() const { return _eventName; };
 protected:
     void* _userData;       ///< User data

cocos/base/CCEventDispatcher.h

@@ -44,8 +44,8 @@ class Node;
 class EventCustom;
 class EventListenerCustom;
 
-/**
+/** @class EventDispatcher
-This class manages event listener subscriptions
+* @brief This class manages event listener subscriptions
 and event dispatching.
 
 The EventListener list is managed in such a way that
@@ -56,7 +56,7 @@ dispatched.
 class CC_DLL EventDispatcher : public Ref
 {
 public:
-    // Adds event listener
+    // Adds event listener.
     
     /** Adds a event listener for a specified event with the priority of scene graph.
      *  @param listener The listener of a specified event.
@@ -76,7 +76,9 @@ public:
 
     /** Adds a Custom event listener.
      It will use a fixed priority of 1.
-     @return the generated event. Needed in order to remove the event from the dispather
+     * @param eventName A given name of the event.
+     * @param callback A given callback method that associated the event name.
+     * @return the generated event. Needed in order to remove the event from the dispather
      */
     EventListenerCustom* addCustomEventListener(const std::string &eventName, const std::function<void(EventCustom*)>& callback);
 
@@ -84,60 +86,98 @@ public:
     
     // Removes event listener
     
-    /** Remove a listener
+    /** Remove a listener.
+     *
      *  @param listener The specified event listener which needs to be removed.
      */
     void removeEventListener(EventListener* listener);
 
-    /** Removes all listeners with the same event listener type */
+    /** Removes all listeners with the same event listener type.
+     *
+     * @param listenerType A given event listener type which needs to be removed.
+     */
     void removeEventListenersForType(EventListener::Type listenerType);
 
-    /** Removes all listeners which are associated with the specified target. */
+    /** Removes all listeners which are associated with the specified target.
+     *
+     * @param target A given target node.
+     * @param recursive True if remove recursively, the default value is false.
+     */
     void removeEventListenersForTarget(Node* target, bool recursive = false);
     
-    /** Removes all custom listeners with the same event name */
+    /** Removes all custom listeners with the same event name.
+     *
+     * @param customEventName A given event listener name which needs to be removed.
+     */
     void removeCustomEventListeners(const std::string& customEventName);
 
-    /** Removes all listeners */
+    /** Removes all listeners.
+     */
     void removeAllEventListeners();
 
     /////////////////////////////////////////////
     
     // Pauses / Resumes event listener
     
-    /** Pauses all listeners which are associated the specified target. */
+    /** Pauses all listeners which are associated the specified target.
+     *
+     * @param target A given target node.
+     * @param recursive True if pause recursively, the default value is false.
+     */
     void pauseEventListenersForTarget(Node* target, bool recursive = false);
     
-    /** Resumes all listeners which are associated the specified target. */
+    /** Resumes all listeners which are associated the specified target.
+     *
+     * @param target A given target node.
+     * @param recursive True if resume recursively, the default value is false.
+     */
     void resumeEventListenersForTarget(Node* target, bool recursive = false);
     
     /////////////////////////////////////////////
     
-    /** Sets listener's priority with fixed value. */
+    /** Sets listener's priority with fixed value.
+     * 
+     * @param listener A given listener.
+     * @param fixedPriority The fixed priority value.
+     */
     void setPriority(EventListener* listener, int fixedPriority);
 
-    /** Whether to enable dispatching events */
+    /** Whether to enable dispatching events.
+     *
+     * @param isEnabled  True if enable dispatching events.
+     */
     void setEnabled(bool isEnabled);
 
-    /** Checks whether dispatching events is enabled */
+    /** Checks whether dispatching events is enabled.
+     *
+     * @return True if dispatching events is enabled.
+     */
     bool isEnabled() const;
 
     /////////////////////////////////////////////
     
-    /** Dispatches the event
+    /** Dispatches the event.
      *  Also removes all EventListeners marked for deletion from the
      *  event dispatcher list.
+     *
+     * @param event The event needs to be dispatched.
      */
     void dispatchEvent(Event* event);
 
-    /** Dispatches a Custom Event with a event name an optional user data */
+    /** Dispatches a Custom Event with a event name an optional user data.
+     *
+     * @param eventName The name of the event which needs to be dispatched.
+     * @param optionalUserData The optional user data, it's a void*, the default value is nullptr.
+     */
     void dispatchCustomEvent(const std::string &eventName, void *optionalUserData = nullptr);
 
     /////////////////////////////////////////////
     
-    /** Constructor of EventDispatcher */
+    /** Constructor of EventDispatcher.
+     */
     EventDispatcher();
-    /** Destructor of EventDispatcher */
+    /** Destructor of EventDispatcher.
+     */
     ~EventDispatcher();
 
 #if CC_NODE_DEBUG_VERIFY_EVENT_LISTENERS && COCOS2D_DEBUG > 0

cocos/base/CCEventFocus.h

@@ -35,9 +35,17 @@ namespace ui {
     class Widget;
 }
 
+/** @class EventFocus
+ * @brief Focus event.
+ */
 class CC_DLL EventFocus : public Event
 {
 public:
+    /** Constructor.
+     *
+     * @param widgetLoseFocus The widget which lose focus.
+     * @param widgetGetFocus The widget which get focus.
+     */
     EventFocus(ui::Widget* widgetLoseFocus, ui::Widget* widgetGetFocus);
     
 private:

cocos/base/CCEventKeyboard.h

@@ -30,11 +30,14 @@
 
 NS_CC_BEGIN
 
+/** @class EventKeyboard
+ * @brief Keyboard event.
+ */
 class CC_DLL EventKeyboard : public Event
 {
 public:
     /**
-     * The key (code).
+     * KeyCode The key (code).
      */
     enum class KeyCode
     {
@@ -210,6 +213,11 @@ public:
         KEY_PLAY
     };
     
+    /** Constructor.
+     *
+     * @param keyCode A given keycode.
+     * @param isPressed True if the key is pressed.
+     */
     EventKeyboard(KeyCode keyCode, bool isPressed);
     
 private:

cocos/base/CCEventListener.h

@@ -37,14 +37,15 @@ NS_CC_BEGIN
 class Event;
 class Node;
 
-/**
+/** @class EventListener
- *  The base class of event listener.
+ *  @brief The base class of event listener.
  *  If you need custom listener which with different callback, you need to inherit this class.
  *  For instance, you could refer to EventListenerAcceleration, EventListenerKeyboard, EventListenerTouchOneByOne, EventListenerCustom.
  */
 class CC_DLL EventListener : public Ref
 {
 public:
+    /** Type Event type.*/
     enum class Type
     {
         UNKNOWN,
@@ -67,24 +68,34 @@ CC_CONSTRUCTOR_ACCESS:
     /** Initializes event with type and callback function */
     bool init(Type t, const ListenerID& listenerID, const std::function<void(Event*)>& callback);
 public:
-    /** Destructor */
+    /** Destructor.
+     */
     virtual ~EventListener();
 
-    /** Checks whether the listener is available. */
+    /** Checks whether the listener is available.
+     * 
+     * @return True if the listener is available.
+     */
     virtual bool checkAvailable() = 0;
 
-    /** Clones the listener, its subclasses have to override this method. */
+    /** Clones the listener, its subclasses have to override this method.
+     */
     virtual EventListener* clone() = 0;
 
-    /** Enables or disables the listener
+    /** Enables or disables the listener.
-     *  @note Only listeners with `enabled` state will be able to receive events.
+     * @note Only listeners with `enabled` state will be able to receive events.
      *        When an listener was initialized, it's enabled by default.
      *        An event listener can receive events when it is enabled and is not paused.
      *        paused state is always false when it is a fixed priority listener.
+     *
+     * @param enabled True if enables the listener.
      */
     inline void setEnabled(bool enabled) { _isEnabled = enabled; };
 
-    /** Checks whether the listener is enabled */
+    /** Checks whether the listener is enabled.
+     *
+     * @return True if the listenrt is enabled.
+     */
     inline bool isEnabled() const { return _isEnabled; };
 
 protected:

cocos/base/CCEventListenerAcceleration.h

@@ -30,12 +30,23 @@
 
 NS_CC_BEGIN
 
+/** @class EventListenerAcceleration
+ * @brief Acceleration event listener.
+ */
 class CC_DLL EventListenerAcceleration : public EventListener
 {
 public:
     static const std::string LISTENER_ID;
     
+    /** Create a acceleration EventListener.
+     *
+     * @param callback The acceleration callback method.
+     * @return An autoreleased EventListenerAcceleration object.
+     */
     static EventListenerAcceleration* create(const std::function<void(Acceleration*, Event*)>& callback);
+    
+    /** Destructor.
+     */
     virtual ~EventListenerAcceleration();
     
     /// Overrides

cocos/base/CCEventListenerController.h

@@ -34,11 +34,18 @@ NS_CC_BEGIN
 class Event;
 class Controller;
 
+/** @class EventListenerController
+ * @param Controller event listener.
+ */
 class EventListenerController : public EventListener
 {
 public:
     static const std::string LISTENER_ID;
     
+    /** Create a controller event listener.
+     *
+     * @return An autoreleased EventListenerController object.
+     */
 	static EventListenerController* create();
     
     /// Overrides

cocos/base/CCEventListenerCustom.h

@@ -31,8 +31,9 @@ NS_CC_BEGIN
 
 class EventCustom;
 
-/**
+/** @class EventListenerCustom
- *  Usage:
+ * @brief Custom event listener.
+ * @code Usage:
  *        auto dispatcher = Director::getInstance()->getEventDispatcher();
  *     Adds a listener:
  *
@@ -53,8 +54,9 @@ class CC_DLL EventListenerCustom : public EventListener
 {
 public:
     /** Creates an event listener with type and callback.
-     *  @param eventType The type of the event.
+     * @param eventType The type of the event.
-     *  @param callback The callback function when the specified event was emitted.
+     * @param callback The callback function when the specified event was emitted.
+     * @return An autoreleased EventListenerCustom object.
      */
     static EventListenerCustom* create(const std::string& eventName, const std::function<void(EventCustom*)>& callback);
     

cocos/base/CCEventListenerFocus.h

@@ -35,12 +35,22 @@ namespace ui {
     class Widget;
 }
 
+/** @class EventListenerFocus
+ * @brief Focus event listener.
+ */
 class CC_DLL EventListenerFocus : public EventListener
 {
 public:
     static const std::string LISTENER_ID;
+    
+    /** Create a focus event listener.
+     *
+     * @return An autoreleased EventListenerFocus object.
+     */
     static EventListenerFocus* create();
     
+    /** Destructor.
+     */
     virtual ~EventListenerFocus();
     
     /// Overrides

cocos/base/CCEventListenerKeyboard.h

@@ -33,11 +33,18 @@ NS_CC_BEGIN
 
 class Event;
 
+/** @class EventListenerKeyboard
+ * @brief Keyboard event listener.
+ */
 class CC_DLL EventListenerKeyboard : public EventListener
 {
 public:
     static const std::string LISTENER_ID;
     
+    /** Create a keyboard event listener.
+     * 
+     * @return An autoreleased EventListenerKeyboard object.
+     */
     static EventListenerKeyboard* create();
     
     /// Overrides

cocos/base/CCEventListenerMouse.h

@@ -33,11 +33,18 @@ NS_CC_BEGIN
 
 class Event;
 
+/** @class EventListenerMouse
+ * @brief Mouse event listener.
+ */
 class CC_DLL EventListenerMouse : public EventListener
 {
 public:
     static const std::string LISTENER_ID;
     
+    /** Create a mouse event listener.
+     *
+     * @return An autoreleased EventListenerMouse object.
+     */
     static EventListenerMouse* create();
 
     /// Overrides

cocos/base/CCEventListenerTouch.h

@@ -34,16 +34,30 @@ NS_CC_BEGIN
 
 class Touch;
 
+/** @class EventListenerTouchOneByOne
+ * @brief Single touch event listener.
+ */
 class CC_DLL EventListenerTouchOneByOne : public EventListener
 {
 public:
     static const std::string LISTENER_ID;
     
+    /** Create a one by one touch event listener.
+     */
     static EventListenerTouchOneByOne* create();
     
+    /** Destructor. */
     virtual ~EventListenerTouchOneByOne();
     
+    /** Whether or not to swall touches.
+     *
+     * @param needSwallow True if needs to swall touches.
+     */
     void setSwallowTouches(bool needSwallow);
+    /** Is swall touches or not.
+     *
+     * @return True if needs to swall touches.
+     */
     bool isSwallowTouches();
     
     /// Overrides
@@ -72,13 +86,21 @@ private:
     friend class EventDispatcher;
 };
 
-
+/** @class EventListenerTouchAllAtOnce
+ * @brief Multiple touches event listener.
+ */
 class CC_DLL EventListenerTouchAllAtOnce : public EventListener
 {
 public:
     static const std::string LISTENER_ID;
     
+    /** Create a all at once event listener.
+     *
+     * @return An autoreleased EventListenerTouchAllAtOnce object.
+     */
     static EventListenerTouchAllAtOnce* create();
+    /** Destructor.
+     */
     virtual ~EventListenerTouchAllAtOnce();
     
     /// Overrides

cocos/base/CCEventMouse.h

@@ -40,11 +40,14 @@
 
 NS_CC_BEGIN
 
+/** @class EventMouse
+ * @brief The mouse event.
+ */
 class CC_DLL EventMouse : public Event
 {
 public:
     /**
-    * Different types of MouseEvent
+    * MouseEventType Different types of MouseEvent.
     */
     enum class MouseEventType
     {
@@ -55,13 +58,34 @@ public:
         MOUSE_SCROLL,
     };
 
+    /** Constructor.
+     *
+     * @param mouseEventCode A given mouse event type.
+     */
     EventMouse(MouseEventType mouseEventCode);
 
-    /** Set mouse scroll data */
+    /** Set mouse scroll data.
+     * 
+     * @param scrollX The scroll data of x axis.
+     * @param scrollY The scroll data of y axis.
+     */
     inline void setScrollData(float scrollX, float scrollY) { _scrollX = scrollX; _scrollY = scrollY; };
+    /** Get mouse scroll data of x axis.
+     * 
+     * @return The scroll data of x axis.
+     */
     inline float getScrollX() { return _scrollX; };
+    /** Get mouse scroll data of y axis.
+     *
+     * @return The scroll data of y axis.
+     */
     inline float getScrollY() { return _scrollY; };
 
+    /** Set the cursor position.
+     *
+     * @param x The x coordinate of cursor position.
+     * @param y The y coordinate of cursor position.
+     */
     inline void setCursorPosition(float x, float y) { 
         _x = x;
         _y = y;
@@ -75,24 +99,61 @@ public:
         }
     }
 
+    /** Set mouse button.
+     * 
+     * @param button a given mouse button.
+     */
     inline void setMouseButton(int button) { _mouseButton = button; };
+    /** Get mouse button.
+     *
+     * @return The mouse button.
+     */
     inline int getMouseButton() { return _mouseButton; };
+    /** Get the cursor position of x axis.
+     *
+     * @return The x coordinate of cursor position.
+     */
     inline float getCursorX() { return _x; };
+    /** Get the cursor position of y axis.
+     *
+     * @return The y coordinate of cursor position.
+     */
     inline float getCursorY() { return _y; };
 
-    /** returns the current touch location in OpenGL coordinates */
+    /** Returns the current touch location in OpenGL coordinates.
+     *
+     * @return The current touch location in OpenGL coordinates.
+     */
     Vec2 getLocation() const;
-    /** returns the previous touch location in OpenGL coordinates */
+    /** Returns the previous touch location in OpenGL coordinates.
+     *
+     * @return The previous touch location in OpenGL coordinates.
+     */
     Vec2 getPreviousLocation() const;
-    /** returns the start touch location in OpenGL coordinates */
+    /** Returns the start touch location in OpenGL coordinates.
+     *
+     * @return The start touch location in OpenGL coordinates.
+     */
     Vec2 getStartLocation() const;
-    /** returns the delta of 2 current touches locations in screen coordinates */
+    /** Returns the delta of 2 current touches locations in screen coordinates.
+     *
+     * @return The delta of 2 current touches locations in screen coordinates.
+     */
     Vec2 getDelta() const;
-    /** returns the current touch location in screen coordinates */
+    /** Returns the current touch location in screen coordinates.
+     *
+     * @return The current touch location in screen coordinates.
+     */
     Vec2 getLocationInView() const;
-    /** returns the previous touch location in screen coordinates */
+    /** Returns the previous touch location in screen coordinates.
+     *
+     * @return The previous touch location in screen coordinates.
+     */
     Vec2 getPreviousLocationInView() const;
-    /** returns the start touch location in screen coordinates */
+    /** Returns the start touch location in screen coordinates.
+     *
+     * @return The start touch location in screen coordinates.
+     */
     Vec2 getStartLocationInView() const;
 
 

cocos/base/CCEventTouch.h

@@ -34,11 +34,15 @@ class Touch;
 
 #define TOUCH_PERF_DEBUG 1
 
+/** @class EventTouch
+ * @brief Touch event.
+ */
 class CC_DLL EventTouch : public Event
 {
 public:
     static const int MAX_TOUCHES = 15;
     
+    /** EventCode Touch event code.*/
     enum class EventCode
     {
         BEGAN,
@@ -47,13 +51,31 @@ public:
         CANCELLED
     };
 
+    /** Constructor.*/
     EventTouch();
 
+    /** Get event code.
+     *
+     * @return The code of the event.
+     */
     inline EventCode getEventCode() const { return _eventCode; };
+    
+    /** Get the touches.
+     *
+     * @return The touches of the event.
+     */
     inline const std::vector<Touch*>& getTouches() const { return _touches; };
 
 #if TOUCH_PERF_DEBUG
+    /** Set the event code.
+     * 
+     * @param eventCode A given EventCode.
+     */
     void setEventCode(EventCode eventCode) { _eventCode = eventCode; };
+    /** Set the touches
+     *
+     * @param touches A given touches vector.
+     */
     void setTouches(const std::vector<Touch*>& touches) { _touches = touches; };
 #endif