Merge pull request #11080 from SuYaoHui/cocosapi

[ci skip]Action,Sprite,TmxTiledMap,UTF8,GLView....

cocos/2d/CCAction.h

@@ -285,17 +285,15 @@ private:
     CC_DISALLOW_COPY_AND_ASSIGN(Speed);
 };
 
-/** 
+/** @class Follow
-@brief Follow is an action that "follows" a node.
+ * @brief Follow is an action that "follows" a node.
-
+ * Eg:
-Eg:
+ * @code
-@code
+ * layer->runAction(Follow::actionWithTarget(hero));
-layer->runAction(Follow::actionWithTarget(hero));
+ * @endcode
-@endcode
+ * Instead of using Camera as a "follower", use this action instead.
-
+ * @since v0.99.2
-Instead of using Camera as a "follower", use this action instead.
+ */
-@since v0.99.2
-*/
 class CC_DLL Follow : public Action
 {
 public:
@@ -307,10 +305,21 @@ public:
      *              with no boundary.
      */
     static Follow* create(Node *followedNode, const Rect& rect = Rect::ZERO);
-    /** Return boundarySet.*/
+    /** Return boundarySet.
+     *
+     * @return Return boundarySet.
+     */
     inline bool isBoundarySet() const { return _boundarySet; }
-    /** Alter behavior - turn on/off boundary. */
+    /** Alter behavior - turn on/off boundary. 
+     *
+     * @param value Turn on/off boundary.
+     */
     inline void setBoundarySet(bool value) { _boundarySet = value; }
+    
+    /** @deprecated Alter behavior - turn on/off boundary. 
+     *
+     * @param value Turn on/off boundary.
+     */
     CC_DEPRECATED_ATTRIBUTE inline void setBoudarySet(bool value) { setBoundarySet(value); }
 
     //

cocos/2d/CCSprite.h

@@ -47,7 +47,7 @@ class Texture2D;
 struct transformValues_;
 
 /**
- * @addtogroup sprite_nodes
+ * @addtogroup _2d
  * @{
  */
 
@@ -94,7 +94,7 @@ public:
      * After creation, the rect of sprite will be the size of the image,
      * and the offset will be (0,0).
      *
-     * @param   filename A path to image file, e.g., "scene1/monster.png"
+     * @param   filename A path to image file, e.g., "scene1/monster.png".
      * @return  An autoreleased sprite object.
      */
     static Sprite* create(const std::string& filename);
@@ -102,9 +102,9 @@ public:
     /**
      * Creates a sprite with an image filename and a rect.
      *
-     * @param   filename A path to image file, e.g., "scene1/monster.png"
+     * @param   filename A path to image file, e.g., "scene1/monster.png".
-     * @param   rect     A subrect of the image file
+     * @param   rect     A subrect of the image file.
-     * @return  An autoreleased sprite object
+     * @return  An autoreleased sprite object.
      */
     static Sprite* create(const std::string& filename, const Rect& rect);
 
@@ -114,7 +114,7 @@ public:
      * After creation, the rect will be the size of the texture, and the offset will be (0,0).
      *
      * @param   texture    A pointer to a Texture2D object.
-     * @return  An autoreleased sprite object
+     * @return  An autoreleased sprite object.
      */
     static Sprite* createWithTexture(Texture2D *texture);
 
@@ -170,7 +170,7 @@ public:
      */
     virtual SpriteBatchNode* getBatchNode() const;
     /**
-     * Sets the batch node to sprite
+     * Sets the batch node to sprite.
      * @warning This method is not recommended for game developers. Sample code for using batch node
      * @code
      * SpriteBatchNode *batch = SpriteBatchNode::create("Images/grossini_dance_atlas.png", 15);
@@ -268,7 +268,7 @@ public:
     /**
      * Whether or not the Sprite needs to be updated in the Atlas.
      *
-     * @return true if the sprite needs to be updated in the Atlas, false otherwise.
+     * @return True if the sprite needs to be updated in the Atlas, false otherwise.
      */
     virtual bool isDirty() const { return _dirty; }
 
@@ -368,21 +368,21 @@ public:
 
     /// @} End of Sprite properties getter/setters
 
-    /** @deprecated Use isFlippedY() instead */
+    /** @deprecated Use isFlippedY() instead. */
     CC_DEPRECATED_ATTRIBUTE bool isFlipY() { return isFlippedY(); };
-    /** @deprecated Use setFlippedY() instead */
+    /** @deprecated Use setFlippedY() instead. */
     CC_DEPRECATED_ATTRIBUTE void setFlipY(bool flippedY) { setFlippedY(flippedY); };
 
     //
     // Overrides
     //
     /// @{
-    /// @name Functions inherited from TextureProtocol
+    /// @name Functions inherited from TextureProtocol.
     /**
     *@code
     *When this function bound into js or lua,the parameter will be changed.
-    *In js: var setBlendFunc(var src, var dst)
+    *In js: var setBlendFunc(var src, var dst).
-    *In lua: local setBlendFunc(local src, local dst)
+    *In lua: local setBlendFunc(local src, local dst).
     *@endcode
     */
     inline void setBlendFunc(const BlendFunc &blendFunc) override { _blendFunc = blendFunc; }

cocos/2d/CCTMXTiledMap.h

@@ -39,87 +39,100 @@ class TMXTilesetInfo;
 class TMXMapInfo;
 
 /**
- * @addtogroup tilemap_parallax_nodes
+ * @addtogroup _2d
  * @{
  */
 
-/** Possible orientations of the TMX map */
+/** Possible orientations of the TMX map. */
 enum
 {
-    /** Orthogonal orientation */
+    /** Orthogonal orientation. */
     TMXOrientationOrtho,
 
-    /** Hexagonal orientation */
+    /** Hexagonal orientation. */
     TMXOrientationHex,
 
-    /** Isometric orientation */
+    /** Isometric orientation. */
     TMXOrientationIso,
     
-    /** Isometric staggered orientation*/
+    /** Isometric staggered orientation. */
     TMXOrientationStaggered,
 };
 
 /** @brief TMXTiledMap knows how to parse and render a TMX map.
 
-It adds support for the TMX tiled map format used by http://www.mapeditor.org
+ * It adds support for the TMX tiled map format used by http://www.mapeditor.org
-It supports isometric, hexagonal and orthogonal tiles.
+ * It supports isometric, hexagonal and orthogonal tiles.
-It also supports object groups, objects, and properties.
+ * It also supports object groups, objects, and properties.
 
-Features:
+ * Features:
-- Each tile will be treated as an Sprite
+ * - Each tile will be treated as an Sprite.
-- The sprites are created on demand. They will be created only when you call "layer->tileAt(position)"
+ * - The sprites are created on demand. They will be created only when you call "layer->tileAt(position)".
-- Each tile can be rotated / moved / scaled / tinted / "opaqued", since each tile is a Sprite
+ * - Each tile can be rotated / moved / scaled / tinted / "opaqued", since each tile is a Sprite.
-- Tiles can be added/removed in runtime
+ * - Tiles can be added/removed in runtime.
-- The z-order of the tiles can be modified in runtime
+ * - The z-order of the tiles can be modified in runtime.
-- Each tile has an anchorPoint of (0,0)
+ * - Each tile has an anchorPoint of (0,0).
-- The anchorPoint of the TMXTileMap is (0,0)
+ * - The anchorPoint of the TMXTileMap is (0,0).
-- The TMX layers will be added as a child
+ * - The TMX layers will be added as a child.
-- The TMX layers will be aliased by default
+ * - The TMX layers will be aliased by default.
-- The tileset image will be loaded using the TextureCache
+ * - The tileset image will be loaded using the TextureCache.
-- Each tile will have a unique tag
+ * - Each tile will have a unique tag.
-- Each tile will have a unique z value. top-left: z=1, bottom-right: z=max z
+ * - Each tile will have a unique z value. top-left: z=1, bottom-right: z=max z.
-- Each object group will be treated as an MutableArray
+ * - Each object group will be treated as an MutableArray.
-- Object class which will contain all the properties in a dictionary
+ * - Object class which will contain all the properties in a dictionary.
-- Properties can be assigned to the Map, Layer, Object Group, and Object
+ * - Properties can be assigned to the Map, Layer, Object Group, and Object.
 
-Limitations:
+ * Limitations:
-- It only supports one tileset per layer.
+ * - It only supports one tileset per layer.
-- Embedded images are not supported
+ * - Embedded images are not supported.
-- It only supports the XML format (the JSON format is not supported)
+ * - It only supports the XML format (the JSON format is not supported).
 
-Technical description:
+ * Technical description:
-Each layer is created using an TMXLayer (subclass of SpriteBatchNode). If you have 5 layers, then 5 TMXLayer will be created,
+ * Each layer is created using an TMXLayer (subclass of SpriteBatchNode). If you have 5 layers, then 5 TMXLayer will be created,
-unless the layer visibility is off. In that case, the layer won't be created at all.
+ * unless the layer visibility is off. In that case, the layer won't be created at all.
-You can obtain the layers (TMXLayer objects) at runtime by:
+ * You can obtain the layers (TMXLayer objects) at runtime by:
-- map->getChildByTag(tag_number);  // 0=1st layer, 1=2nd layer, 2=3rd layer, etc...
+ * - map->getChildByTag(tag_number);  // 0=1st layer, 1=2nd layer, 2=3rd layer, etc...
-- map->getLayer(name_of_the_layer);
+ * - map->getLayer(name_of_the_layer);
 
-Each object group is created using a TMXObjectGroup which is a subclass of MutableArray.
+ * Each object group is created using a TMXObjectGroup which is a subclass of MutableArray.
-You can obtain the object groups at runtime by:
+ * You can obtain the object groups at runtime by:
-- map->getObjectGroup(name_of_the_object_group);
+ * - map->getObjectGroup(name_of_the_object_group);
 
-Each object is a TMXObject.
+ * Each object is a TMXObject.
 
-Each property is stored as a key-value pair in an MutableDictionary.
+ * Each property is stored as a key-value pair in an MutableDictionary.
-You can obtain the properties at runtime by:
+ * You can obtain the properties at runtime by:
 
-map->getProperty(name_of_the_property);
+ * map->getProperty(name_of_the_property);
-layer->getProperty(name_of_the_property);
+ * layer->getProperty(name_of_the_property);
-objectGroup->getProperty(name_of_the_property);
+ * objectGroup->getProperty(name_of_the_property);
-object->getProperty(name_of_the_property);
+ * object->getProperty(name_of_the_property);
 
-@since v0.8.1
+ * @since v0.8.1
-*/
+ */
 class CC_DLL TMXTiledMap : public Node
 {
 public:
-    /** creates a TMX Tiled Map with a TMX file.*/
+    /** Creates a TMX Tiled Map with a TMX file.
+     *
+     * @param tmxFile A TMX file.
+     * @return An autorelease object.
+     */
     static TMXTiledMap* create(const std::string& tmxFile);
 
-    /** initializes a TMX Tiled Map with a TMX formatted XML string and a path to TMX resources */
+    /** Initializes a TMX Tiled Map with a TMX formatted XML string and a path to TMX resources. 
+     *
+     * @param tmxString A TMX formatted XML string.
+     * @param resourcePath The path to TMX resources.
+     * @return An autorelease object.
+     */
     static TMXTiledMap* createWithXML(const std::string& tmxString, const std::string& resourcePath);
 
-    /** return the TMXLayer for the specific layer */
+    /** Return the TMXLayer for the specific layer. 
+     *
+     * @param layerName A specific layer.
+     * @return The TMXLayer for the specific layer.
+     */
     TMXLayer* getLayer(const std::string& layerName) const;
     /**
      * @js NA
@@ -127,7 +140,11 @@ public:
      */
     CC_DEPRECATED_ATTRIBUTE TMXLayer* layerNamed(const std::string& layerName) const { return getLayer(layerName); };
 
-    /** return the TMXObjectGroup for the specific group */
+    /** Return the TMXObjectGroup for the specific group. 
+     *
+     * @param groupName The group Name.
+     * @return A Type of TMXObjectGroup.
+     */
     TMXObjectGroup* getObjectGroup(const std::string& groupName) const;
     /**
      * @js NA
@@ -135,7 +152,11 @@ public:
      */
     CC_DEPRECATED_ATTRIBUTE TMXObjectGroup* objectGroupNamed(const std::string& groupName) const { return getObjectGroup(groupName); };
 
-    /** return the value for the specific property name */
+    /** Return the value for the specific property name. 
+     *
+     * @param propertyName The specific property name.
+     * @return Return the value for the specific property name.
+     */
     Value getProperty(const std::string& propertyName) const;
     /**
      * @js NA
@@ -143,40 +164,89 @@ public:
      */
     CC_DEPRECATED_ATTRIBUTE Value propertyNamed(const char *propertyName) const { return getProperty(propertyName); };
 
-    /** return properties dictionary for tile GID */
+    /** Return properties dictionary for tile GID. 
+     *
+     * @param GID The tile GID.
+     * @return Return properties dictionary for tile GID.
+     */
     Value getPropertiesForGID(int GID) const;
     CC_DEPRECATED_ATTRIBUTE Value propertiesForGID(int GID) const { return getPropertiesForGID(GID); };
 
     /** Assings properties to argument value, returns true if it did found properties 
-        for that GID and did assinged a value, else it returns false.
+     * for that GID and did assinged a value, else it returns false.
+     *
+     * @param GID The tile GID.
+     * @param value Argument value.
+     * @return Return true if it did found properties for that GID and did assinged a value, else it returns false.
      */
     bool getPropertiesForGID(int GID, Value** value);
 
-    /** the map's size property measured in tiles */
+    /** The map's size property measured in tiles. 
+     *
+     * @return The map's size property measured in tiles.
+     */
     inline const Size& getMapSize() const { return _mapSize; };
+    
+    /** Set the map's size property measured in tiles. 
+     *
+     * @param mapSize The map's size property measured in tiles.
+     */
     inline void setMapSize(const Size& mapSize) { _mapSize = mapSize; };
 
-    /** the tiles's size property measured in pixels */
+    /** The tiles's size property measured in pixels. 
+     *
+     * @return The tiles's size property measured in pixels.
+     */
     inline const Size& getTileSize() const { return _tileSize; };
+    
+    /** Set the tiles's size property measured in pixels. 
+     *
+     * @param The tiles's size property measured in pixels.
+     */
     inline void setTileSize(const Size& tileSize) { _tileSize = tileSize; };
 
-    /** map orientation */
+    /** Map orientation. 
+     *
+     * @return Map orientation.
+     */
     inline int getMapOrientation() const { return _mapOrientation; };
+    
+    /** Set map orientation. 
+     *
+     * @param mapOrientation The map orientation.
+     */
     inline void setMapOrientation(int mapOrientation) { _mapOrientation = mapOrientation; };
 
-    /** object groups */
+    /** Get the Object groups. 
+     *
+     * @return The object groups.
+     */
     inline const Vector<TMXObjectGroup*>& getObjectGroups() const { return _objectGroups; };
     inline Vector<TMXObjectGroup*>& getObjectGroups() { return _objectGroups; };
+    
+    /** Set the object groups. 
+     *
+     * @param groups The object groups.
+     */
     inline void setObjectGroups(const Vector<TMXObjectGroup*>& groups) {
         _objectGroups = groups;
     };
     
-    /** properties */
+    /** Properties. 
+     *
+     * @return Properties.
+     */
     inline ValueMap& getProperties() { return _properties; };
+    
+    /** Set the properties.
+     *
+     * @param properties A  Type of ValueMap to set the properties.
+     */
     inline void setProperties(const ValueMap& properties) {
         _properties = properties;
     };
-
+    
+    /** Get the description. */
     virtual std::string getDescription() const override;
     
 CC_CONSTRUCTOR_ACCESS:

cocos/base/ccUTF8.h

@@ -35,10 +35,10 @@ NS_CC_BEGIN
 namespace StringUtils {
 
 /**
- *  @brief Converts utf8 string to utf16 string
+ *  @brief Converts utf8 string to utf16 string.
- *  @param utf8 The utf8 string to be converted
+ *  @param utf8 The utf8 string to be converted.
- *  @param outUtf16 The output utf16 string
+ *  @param outUtf16 The output utf16 string.
- *  @return true if succeed, otherwise false
+ *  @return True if succeed, otherwise false.
  *  @note Please check the return value before using \p outUtf16
  *  e.g.
  *  @code
@@ -52,10 +52,10 @@ namespace StringUtils {
 CC_DLL bool UTF8ToUTF16(const std::string& utf8, std::u16string& outUtf16);
 
 /**
- *  @brief Converts utf16 string to utf8 string
+ *  @brief Converts utf16 string to utf8 string.
- *  @param utf16 The utf16 string to be converted
+ *  @param utf16 The utf16 string to be converted.
- *  @param outUtf8 The output utf8 string
+ *  @param outUtf8 The output utf8 string.
- *  @return true if succeed, otherwise false
+ *  @return True if succeed, otherwise false.
  *  @note Please check the return value before using \p outUtf8
  *  e.g.
  *  @code
@@ -69,15 +69,14 @@ CC_DLL bool UTF8ToUTF16(const std::string& utf8, std::u16string& outUtf16);
 CC_DLL bool UTF16ToUTF8(const std::u16string& utf16, std::string& outUtf8);
 
 /**
- *  @brief Trims the unicode spaces at the end of char16_t vector
+ *  @brief Trims the unicode spaces at the end of char16_t vector.
  */
 CC_DLL void trimUTF16Vector(std::vector<char16_t>& str);
 
 /**
  *  @brief Whether the character is a whitespace character.
- *
+ *  @param ch    The unicode character.
- *  @param ch    the unicode character
+ *  @returns     Whether the character is a white space character.
- *  @returns     whether the character is a white space character.
  *
  *  @see http://en.wikipedia.org/wiki/Whitespace_character#Unicode
  *
@@ -86,9 +85,8 @@ CC_DLL bool isUnicodeSpace(char16_t ch);
 
 /**
  *  @brief Whether the character is a Chinese/Japanese/Korean character.
- *
+ *  @param ch    The unicode character.
- *  @param ch    the unicode character
+ *  @returns     Whether the character is a Chinese character.
- *  @returns     whether the character is a Chinese character.
  *
  *  @see http://www.searchtb.com/2012/04/chinese_encode.html
  *  @see http://tieba.baidu.com/p/748765987
@@ -98,39 +96,35 @@ CC_DLL bool isCJKUnicode(char16_t ch);
 
 /**
  *  @brief Returns the length of the string in characters.
- *
+ *  @param utf8 An UTF-8 encoded string.
- *  @param utf8 an UTF-8 encoded string.
+ *  @returns The length of the string in characters.
- *  @returns the length of the string in characters
  */
 CC_DLL long getCharacterCountInUTF8String(const std::string& utf8);
 
 /**
  *  @brief Gets the index of the last character that is not equal to the character given.
- *
+ *  @param str   The string to be searched.
- *  @param str   the string to be searched.
+ *  @param c     The character to be searched for.
- *  @param c     the character to be searched for.
+ *  @returns The index of the last character that is not \p c.
- *
- *  @returns the index of the last character that is not \p c.
- *
  */
 CC_DLL unsigned int getIndexOfLastNotChar16(const std::vector<char16_t>& str, char16_t c);
 
 /**
- *  @brief Gets char16_t vector from a given utf16 string
+ *  @brief Gets char16_t vector from a given utf16 string.
  */
 CC_DLL std::vector<char16_t> getChar16VectorFromUTF16String(const std::u16string& utf16);
 
 } // namespace StringUtils {
 
 /**
- * Returns the character count in UTF16 string
+ * Returns the character count in UTF16 string.
- * @param str pointer to the start of a UTF-16 encoded string. It must be an NULL terminal UTF8 string.
+ * @param str Pointer to the start of a UTF-16 encoded string. It must be an NULL terminal UTF8 string.
- * @deprecated Please use c++11 `std::u16string::length` instead, don't use `unsigned short*` directly
+ * @deprecated Please use c++11 `std::u16string::length` instead, don't use `unsigned short*` directly.
  */
 CC_DEPRECATED_ATTRIBUTE CC_DLL int cc_wcslen(const unsigned short* str);
 
-/** Trims the space characters at the end of UTF8 string 
+/** Trims the space characters at the end of UTF8 string.
- *  @deprecated Please use `StringUtils::trimUTF16Vector` instead
+ *  @deprecated Please use `StringUtils::trimUTF16Vector` instead.
  */
 
 CC_DEPRECATED_ATTRIBUTE CC_DLL void cc_utf8_trim_ws(std::vector<unsigned short>* str);
@@ -138,75 +132,76 @@ CC_DEPRECATED_ATTRIBUTE CC_DLL void cc_utf8_trim_ws(std::vector<unsigned short>*
 /**
  * Whether the character is a whitespace character.
  *
- * @param ch    the unicode character
+ * @param ch    The unicode character.
- * @returns     whether the character is a white space character.
+ * @returns     Whether the character is a white space character.
- * @deprecated Please use `StringUtils::isUnicodeSpace` instead
+ * @deprecated Please use `StringUtils::isUnicodeSpace` instead.
  *
  * @see http://en.wikipedia.org/wiki/Whitespace_character#Unicode
- * */
+ */
 CC_DEPRECATED_ATTRIBUTE CC_DLL bool isspace_unicode(unsigned short ch);
 
 /**
  * Whether the character is a Chinese/Japanese/Korean character.
  *
- * @param ch    the unicode character
+ * @param ch    The unicode character
- * @returns     whether the character is a Chinese character.
+ * @returns     Whether the character is a Chinese character.
- * @deprecated Please use `StringUtils::isCJKUnicode` instead
+ * @deprecated Please use `StringUtils::isCJKUnicode` instead.
  *
  * @see http://www.searchtb.com/2012/04/chinese_encode.html
  * @see http://tieba.baidu.com/p/748765987
- * */
+ */
 CC_DEPRECATED_ATTRIBUTE CC_DLL bool iscjk_unicode(unsigned short ch);
 
 /**
  * Returns the length of the string in characters.
  *
- * @param p pointer to the start of a UTF-8 encoded string. It must be an NULL terminal UTF8 string.
+ * @param p Pointer to the start of a UTF-8 encoded string. It must be an NULL terminal UTF8 string.
- * @param max Not used from 3.1, just keep it for backward compatibility
+ * @param max Not used from 3.1, just keep it for backward compatibility.
- * @deprecated Please use `StringUtils::getCharacterCountInUTF8String` instead
+ * @deprecated Please use `StringUtils::getCharacterCountInUTF8String` instead.
- * @returns the length of the string in characters
+ * @returns The length of the string in characters.
  **/
 CC_DEPRECATED_ATTRIBUTE CC_DLL long cc_utf8_strlen (const char * p, int max = -1);
 
 /**
  * Find the last character that is not equal to the character given.
  *
- * @param str   the string to be searched.
+ * @param str   The string to be searched.
- * @param c     the character to be searched for.
+ * @param c     The character to be searched for.
- * @deprecated Please use `StringUtils::getIndexOfLastNotChar16` instead
+ * @deprecated Please use `StringUtils::getIndexOfLastNotChar16` instead.
- * @returns the index of the last character that is not \p c.
+ * @returns The index of the last character that is not \p c.
- * */
+ */
 CC_DEPRECATED_ATTRIBUTE CC_DLL unsigned int cc_utf8_find_last_not_char(const std::vector<unsigned short>& str, unsigned short c);
 
 /**
- *  @brief Gets `unsigned short` vector from a given utf16 string
+ *  @brief Gets `unsigned short` vector from a given utf16 string.
- *  @deprecated Please use `StringUtils::getChar16VectorFromUTF16String` instead
+ *  @param str A given utf16 string.
+ *  @deprecated Please use `StringUtils::getChar16VectorFromUTF16String` instead.
  */
 CC_DEPRECATED_ATTRIBUTE CC_DLL std::vector<unsigned short> cc_utf16_vec_from_utf16_str(const unsigned short* str);
 
 /**
  * Creates an utf8 string from a c string. The result will be null terminated.
  *
- * @param str_old pointer to the start of a C string. It must be an NULL terminal UTF8 string.
+ * @param str_old Pointer to the start of a C string. It must be an NULL terminal UTF8 string.
- * @param length  not used from 3.1, keep it just for backward compatibility
+ * @param length  Not used from 3.1, keep it just for backward compatibility.
  * @param rUtf16Size The character count in the return UTF16 string.
- * @deprecated Please use `StringUtils::UTF8ToUTF16` instead
+ * @deprecated Please use `StringUtils::UTF8ToUTF16` instead.
- * @returns the newly created utf16 string, it must be released with `delete[]`,
+ * @returns The newly created utf16 string, it must be released with `delete[]`,
  *          If an error occurs, %NULL will be returned.
- * */
+ */
 CC_DEPRECATED_ATTRIBUTE CC_DLL unsigned short* cc_utf8_to_utf16(const char* str_old, int length = -1, int* rUtf16Size = nullptr);
 
 /**
  * Converts a string from UTF-16 to UTF-8. The result will be null terminated.
  *
- * @param utf16 an UTF-16 encoded string, It must be an NULL terminal UTF16 string.
+ * @param utf16 An UTF-16 encoded string, It must be an NULL terminal UTF16 string.
- * @param len not used from 3.1, keep it just for backward compatibility
+ * @param len Not used from 3.1, keep it just for backward compatibility.
- * @param items_read     not used from 3.1, keep it just for backward compatibility
+ * @param items_read     Not used from 3.1, keep it just for backward compatibility.
- * @param items_written  not used from 3.1, keep it just for backward compatibility
+ * @param items_written  Not used from 3.1, keep it just for backward compatibility.
- * @deprecated Please use `StringUtils::UTF16ToUTF8` instead
+ * @deprecated Please use `StringUtils::UTF16ToUTF8` instead.
- * @returns a pointer to a newly allocated UTF-8 string. This value must be
+ * @returns A pointer to a newly allocated UTF-8 string. This value must be
  *          released with `delete[]`. If an error occurs, %NULL will be returned.
- **/
+ */
 CC_DEPRECATED_ATTRIBUTE CC_DLL char * cc_utf16_to_utf8 (const unsigned short  *str,
                   int             len = -1,
                   long            *items_read = nullptr,
@@ -215,4 +210,4 @@ CC_DEPRECATED_ATTRIBUTE CC_DLL char * cc_utf16_to_utf8 (const unsigned short  *s
 
 NS_CC_END
 
-#endif /* defined(__cocos2dx__ccUTF8__) */
+#endif /** defined(__cocos2dx__ccUTF8__) */

cocos/platform/CCGLView.h

@@ -39,31 +39,38 @@ THE SOFTWARE.
 typedef void* id;
 #endif /* (CC_TARGET_PLATFORM == CC_PLATFORM_MAC) */
 
+/** There are some Resolution Policy for Adapt to the screen. */
 enum class ResolutionPolicy
 {
-    // The entire application is visible in the specified area without trying to preserve the original aspect ratio.
+    /** The entire application is visible in the specified area without trying to preserve the original aspect ratio.
-    // Distortion can occur, and the application may appear stretched or compressed.
+     * Distortion can occur, and the application may appear stretched or compressed.
+     */
     EXACT_FIT,
-    // The entire application fills the specified area, without distortion but possibly with some cropping,
+    /** The entire application fills the specified area, without distortion but possibly with some cropping,
-    // while maintaining the original aspect ratio of the application.
+     * while maintaining the original aspect ratio of the application.
+     */
     NO_BORDER,
-    // The entire application is visible in the specified area without distortion while maintaining the original
+    /** The entire application is visible in the specified area without distortion while maintaining the original
-    // aspect ratio of the application. Borders can appear on two sides of the application.
+     * aspect ratio of the application. Borders can appear on two sides of the application.
+     */
     SHOW_ALL,
-    // The application takes the height of the design resolution size and modifies the width of the internal
+    /** The application takes the height of the design resolution size and modifies the width of the internal
-    // canvas so that it fits the aspect ratio of the device
+     * canvas so that it fits the aspect ratio of the device.
-    // no distortion will occur however you must make sure your application works on different
+     * No distortion will occur however you must make sure your application works on different
-    // aspect ratios
+     * aspect ratios.
+     */
     FIXED_HEIGHT,
-    // The application takes the width of the design resolution size and modifies the height of the internal
+    /** The application takes the width of the design resolution size and modifies the height of the internal
-    // canvas so that it fits the aspect ratio of the device
+     * canvas so that it fits the aspect ratio of the device.
-    // no distortion will occur however you must make sure your application works on different
+     * No distortion will occur however you must make sure your application works on different
-    // aspect ratios
+     * aspect ratios.
+     */
     FIXED_WIDTH,
 
     UNKNOWN,
 };
 
+/** @struct GLContextAttrs Have six opengl Context Attrs. */
 struct GLContextAttrs
 {
     int redBits;
@@ -80,7 +87,9 @@ NS_CC_BEGIN
  * @addtogroup platform
  * @{
  */
-
+/**
+ * @brief By GLView you can operate the frame information of EGL view through some function.
+ */
 class CC_DLL GLView : public Ref
 {
 public:
@@ -103,56 +112,100 @@ public:
     /** Exchanges the front and back buffers, subclass must implement this method. */
     virtual void swapBuffers() = 0;
 
-    /** Open or close IME keyboard , subclass must implement this method. */
+    /** Open or close IME keyboard , subclass must implement this method. 
+     *
+     * @param open Open or close IME keyboard.
+     */
     virtual void setIMEKeyboardState(bool open) = 0;
 
 #if (CC_TARGET_PLATFORM == CC_PLATFORM_WP8 || CC_TARGET_PLATFORM == CC_PLATFORM_WINRT)
     virtual void setIMEKeyboardState(bool open, std::string str) = 0;
 #endif
     
+    /** When the window is closed, it will return false if the platforms is Ios or Android.
+     * If the platforms is windows or Mac,it will return true.
+     *
+     * @return In ios and android it will return false,if in windows or Mac it will return true.
+     */
     virtual bool windowShouldClose() { return false; };
 
-    //static method and member so that we can modify it on all platforms before create OpenGL context
+    /** Static method and member so that we can modify it on all platforms before create OpenGL context. 
+     *
+     * @param glContextAttrs The OpenGL context attrs.
+     */
     static void setGLContextAttrs(GLContextAttrs& glContextAttrs);
+    
+    /** Return the OpenGL context attrs. 
+     *
+     * @return Return the OpenGL context attrs.
+     */
     static GLContextAttrs getGLContextAttrs();
+    
+    /** The OpenGL context attrs. */
     static GLContextAttrs _glContextAttrs;
 
-    /**
+    /** @deprecated
      * Polls input events. Subclass must implement methods if platform
      * does not provide event callbacks.
      */
     CC_DEPRECATED_ATTRIBUTE virtual void pollInputEvents();
-
+    
+    /** Polls the events. */
     virtual void pollEvents();
 
     /**
      * Get the frame size of EGL view.
      * In general, it returns the screen size since the EGL view is a fullscreen view.
+     *
+     * @return The frame size of EGL view.
      */
     virtual const Size& getFrameSize() const;
 
     /**
      * Set the frame size of EGL view.
+     *
+     * @param width The width of the fram size.
+     * @param height The height of the fram size.
      */
     virtual void setFrameSize(float width, float height);
 
-    /** Set and get zoom factor for frame. This two methods are for
+    /** Set zoom factor for frame. This methods are for
-     debugging big resolution (e.g.new ipad) app on desktop.*/
+     * debugging big resolution (e.g.new ipad) app on desktop.
+     * 
+     * @param zoomFactor The zoom factor for frame.
+     */
     virtual void setFrameZoomFactor(float zoomFactor) {}
+    
+    /** Get zoom factor for frame. This methods are for
+     * debugging big resolution (e.g.new ipad) app on desktop.
+     *
+     * @return The zoom factor for frame.
+     */
     virtual float getFrameZoomFactor() const { return 1.0; }
+    
     /**
      * Hide or Show the mouse cursor if there is one.
+     *
+     * @param isVisible Hide or Show the mouse cursor if there is one.
      */
     virtual void setCursorVisible(bool isVisible) {}
 
-    /** Get retina factor */
+    /** Get retina factor.
+     *
+     * @return The retina factor.
+     */
     virtual int getRetinaFactor() const { return 1; }
 
-    /** only works on ios platform*/
+    /** Only works on ios platform. Set Content Scale of the Factor. */
     virtual bool setContentScaleFactor(float scaleFactor) { return false; }
+    
+    /** Only works on ios platform. Get Content Scale of the Factor. */
     virtual float getContentScaleFactor() const { return 1.0; }
     
-    /** returns whether or not the view is in Retina Display mode */
+    /** Returns whether or not the view is in Retina Display mode.
+     *
+     * @return Returns whether or not the view is in Retina Display mode.
+     */
     virtual bool isRetinaDisplay() const { return false; }
  
 #if (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)
@@ -166,16 +219,22 @@ public:
 #endif
     /**
      * Get the visible area size of opengl viewport.
+     *
+     * @return The visible area size of opengl viewport.
      */
     virtual Size getVisibleSize() const;
 
     /**
      * Get the visible origin point of opengl viewport.
+     *
+     * @return The visible origin point of opengl viewport.
      */
     virtual Vec2 getVisibleOrigin() const;
 
     /**
      * Get the visible rectangle of opengl viewport.
+     *
+     * @return The visible rectangle of opengl viewport.
      */
     virtual Rect getVisibleRect() const;
 
@@ -192,59 +251,125 @@ public:
 
     /** Get design resolution size.
      *  Default resolution size is the same as 'getFrameSize'.
+     *
+     * @return The design resolution size.
      */
     virtual const Size&  getDesignResolutionSize() const;
 
     /**
      * Set opengl view port rectangle with points.
+     *
+     * @param x Set the points of x.
+     * @param y Set the points of y.
+     * @param w Set the width of  the view port
+     * @param h Set the Height of the view port.
      */
     virtual void setViewPortInPoints(float x , float y , float w , float h);
 
     /**
      * Set Scissor rectangle with points.
+     *
+     * @param x Set the points of x.
+     * @param y Set the points of y.
+     * @param w Set the width of  the view port
+     * @param h Set the Height of the view port.
      */
     virtual void setScissorInPoints(float x , float y , float w , float h);
 
     /**
-     * Get whether GL_SCISSOR_TEST is enable
+     * Get whether GL_SCISSOR_TEST is enable.
+     *
+     * @return Whether GL_SCISSOR_TEST is enable.
      */
     virtual bool isScissorEnabled();
 
     /**
-     * Get the current scissor rectangle
+     * Get the current scissor rectangle.
+     *
+     * @return The current scissor rectangle.
      */
     virtual Rect getScissorRect() const;
 
+    /** Set the view name. 
+     *
+     * @param viewname A string will be set to the view as name.
+     */
     virtual void setViewName(const std::string& viewname);
+    
+    /** Get the view name.
+     *
+     * @return The view name.
+     */
     const std::string& getViewName() const;
 
-    /** Touch events are handled by default; if you want to customize your handlers, please override these functions: */
+    /** Touch events are handled by default; if you want to customize your handlers, please override this function.
+     *
+     * @param num The number of touch.
+     * @param ids The identity of the touch.
+     * @param xs The points of x.
+     * @param ys The points of y.
+     */
     virtual void handleTouchesBegin(int num, intptr_t ids[], float xs[], float ys[]);
+    
+    /** Touch events are handled by default; if you want to customize your handlers, please override this function.
+     *
+     * @param num The number of touch.
+     * @param ids The identity of the touch.
+     * @param xs The points of x.
+     * @param ys The points of y.
+     */
     virtual void handleTouchesMove(int num, intptr_t ids[], float xs[], float ys[]);
+    
+    /** Touch events are handled by default; if you want to customize your handlers, please override this function.
+     *
+     * @param num The number of touch.
+     * @param ids The identity of the touch.
+     * @param xs The points of x.
+     * @param ys The points of y.
+     */
     virtual void handleTouchesEnd(int num, intptr_t ids[], float xs[], float ys[]);
+    
+    /** Touch events are handled by default; if you want to customize your handlers, please override this function.
+     *
+     * @param num The number of touch.
+     * @param ids The identity of the touch.
+     * @param xs The points of x.
+     * @param ys The points of y.
+     */
     virtual void handleTouchesCancel(int num, intptr_t ids[], float xs[], float ys[]);
 
     /**
      * Get the opengl view port rectangle.
+     *
+     * @return Return the opengl view port rectangle.
      */
     const Rect& getViewPortRect() const;
     
     /**
-     * Get list of all active touches
+     * Get list of all active touches.
+     *
+     * @return A list of all active touches.
      */
     std::vector<Touch*> getAllTouches() const;
 
     /**
      * Get scale factor of the horizontal direction.
+     *
+     * @return Scale factor of the horizontal direction.
      */
     float getScaleX() const;
 
     /**
      * Get scale factor of the vertical direction.
+     *
+     * @return Scale factor of the vertical direction.
      */
     float getScaleY() const;
 
-    /** returns the current Resolution policy */
+    /** Returns the current Resolution policy.
+     *
+     * @return The current Resolution policy.
+     */
     ResolutionPolicy getResolutionPolicy() const { return _resolutionPolicy; }
 
 #if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)