Merge pull request #11135 from fusijie/cocosapi

[ci skip]add comments.

cocos/ui/UIText.h

@@ -28,6 +28,11 @@ THE SOFTWARE.
 #include "ui/UIWidget.h"
 #include "ui/GUIExport.h"
 
+/**
+ * @addtogroup ui
+ * @{
+ */
+
 NS_CC_BEGIN
 
 class Label;
@@ -45,31 +50,40 @@ class CC_GUI_DLL Text : public Widget
     DECLARE_CLASS_GUI_INFO
     
 public:
+    /** Type Text type.
+     */
     enum class Type
     {
         SYSTEM,
         TTF
     };
     /**
-     * Default constructor
+     * Default constructor.
      */
     Text();
 
     /**
-     * Default destructor
+     * Default destructor.
      */
     virtual ~Text();
 
     /**
-     * Allocates and initializes.
+     * Create a Text object.
+     *
+     * @return An autoreleased Text object.
      */
     static Text* create();
     
     /**
-     *  create a Text object with textContent, fontName and fontSize
+     *  Create a Text object with textContent, fontName and fontSize.
-     *  the fontName could be a system font name or a TTF file path.
+     *  The fontName could be a system font name or a TTF file path.
-     *  Usage:  Text *text = Text::create("Hello", "Arial", 20);  //create a system font UIText
+     *  Usage:  Text *text = Text::create("Hello", "Arial", 20);  //create a system font UIText.
-     *          Text *text = Text::create("Hello", "xxx\xxx.ttf", 20); //create a TTF font UIText
+     *          Text *text = Text::create("Hello", "xxx\xxx.ttf", 20); //create a TTF font UIText.
+     *
+     * @param textContent Text content string.
+     * @param fontName A given font name.
+     * @param fontSize A given font size.
+     * @return An autoreleased Text object.
      */
     static Text* create(const std::string& textContent,
                         const std::string& fontName,
@@ -78,7 +92,7 @@ public:
     /**
      * Changes the string value of label.
      *
-     * @param text  string value.
+     * @param text  String value.
      */
     CC_DEPRECATED_ATTRIBUTE void setText(const std::string& text){this->setString(text);}
     void setString(const std::string& text);
@@ -86,7 +100,7 @@ public:
     /**
      * Gets the string value of label.
      *
-     * @return string value.
+     * @return String value.
      */
     CC_DEPRECATED_ATTRIBUTE const std::string& getStringValue(){ return this->getString();}
     const std::string& getString()const;
@@ -94,19 +108,24 @@ public:
     /**
      * Gets the string length of the label.
      * Note: This length will be larger than the raw string length,
-     * if you want to get the raw string length, you should call this->getString().size() instead
+     * if you want to get the raw string length, you should call this->getString().size() instead.
      *
-     * @return  string length.
+     * @return  String length.
      */
     ssize_t getStringLength()const;
 
     /**
      * Sets the font size of label.
      *
-     * @param size font size.
+     * @param size The font size.
      */
     void setFontSize(int size);
 
+    /**
+     * Gets the font size of label.
+     *
+     * @return The font size.
+     */
     int getFontSize()const;
 
     /**
@@ -116,25 +135,32 @@ public:
      * Usage:  Text *text = Text::create("Hello", "Arial", 20);  //create a system font UIText
      *         text->setFontName("Marfelt");  // it will change the font  to  system font no matter the previous font type is TTF or system font
      *         text->setFontName("xxxx/xxx.ttf"); //it will change the font  to TTF font no matter the previous font type is TTF or system font
-     * @param name font name.
+     * @param name Font name.
      */
     void setFontName(const std::string& name);
 
+    /** Gets the font name.
+     *
+     * @return Font name.
+     */
     const std::string& getFontName()const;
     
+    /** Gets the font type.
+     * @return The font type.
+     */
     Type getType() const;
 
     /**
      * Sets the touch scale enabled of label.
      *
-     * @param enabled touch scale enabled of label.
+     * @param enabled Touch scale enabled of label.
      */
     void setTouchScaleChangeEnabled(bool enabled);
 
     /**
      * Gets the touch scale enabled of label.
      *
-     * @return  touch scale enabled of label.
+     * @return  Touch scale enabled of label.
      */
     bool isTouchScaleChangeEnabled()const;
 
@@ -144,6 +170,10 @@ public:
     //override "getVirtualRenderer" method of widget.
     virtual Node* getVirtualRenderer() override;
 
+    /** Gets the render size in auto mode.
+     *
+     * @return The size of render size in auto mode.
+     */
     virtual Size getAutoRenderSize();
 
     /**
@@ -152,45 +182,85 @@ public:
     virtual std::string getDescription() const override;
 
     /**
-     * Set the rendering size of the text, you should call this method
+     * Sets the rendering size of the text, you should call this method
      * along with calling `ignoreContentAdaptWithSize(false)`, otherwise the text area
-     * size is caculated by the real size of the text content
+     * size is caculated by the real size of the text content.
-     * @param size   The text rendering area size
+     *
+     * @param size The text rendering area size.
      *
      */
     void setTextAreaSize(const Size &size);
 
+    /** Return the text rendering area size.
+     *
+     * @return The text rendering area size.
+     */
     const Size& getTextAreaSize()const;
 
+    /** Sets text horizontal alignment.
+     *
+     * @param alignment Horizontal text alignment type
+     */
     void setTextHorizontalAlignment(TextHAlignment alignment);
 
+    /** Gets text horizontal alignment.
+     *
+     * @return Horizontal text alignment type
+     */
     TextHAlignment getTextHorizontalAlignment()const;
 
+    /** Sets text vertical alignment.
+     *
+     * @param alignment vertical text alignment type
+     */
     void setTextVerticalAlignment(TextVAlignment alignment);
 
+    /** Gets text vertical alignment.
+     *
+     * @return Vertical text alignment type
+     */
     TextVAlignment getTextVerticalAlignment()const;
     
+    /** Sets text color.
+     *
+     * @param color Text color.
+     */
     void setTextColor(const Color4B color);
     
+    /** Gets text color.
+     *
+     * @return Text color.
+     */
     const Color4B& getTextColor() const;
     
     /**
-     * Enable shadow for the label
+     * Enable shadow for the label.
      *
      * @todo support blur for shadow effect
+     *
+     * @param shadowColor The color of shadow effect.
+     * @param offset The offset of shadow effect.
+     * @param blurRadius The blur radius of shadow effect.
      */
     void enableShadow(const Color4B& shadowColor = Color4B::BLACK,const Size &offset = Size(2,-2), int blurRadius = 0);
     
     /**
-     * Enable outline for the label
+     * Enable outline for the label.
-     * It only works on IOS and Android when you use System fonts
+     * It only works on IOS and Android when you use System fonts.
+     *
+     * @param outlineColor The color of outline.
+     * @param outlineSize The size of outline.
      */ 
     void enableOutline(const Color4B& outlineColor,int outlineSize = 1);
     
-    /** only support for TTF */
+    /** Only support for TTF.
+     *
+     * @param glowColor The color of glow.
+     */
     void enableGlow(const Color4B& glowColor);
     
-    /** disable shadow/outline/glow rendering */
+    /** Disable shadow/outline/glow rendering.
+     */
     void disableEffect();
     
 CC_CONSTRUCTOR_ACCESS:
@@ -226,4 +296,7 @@ protected:
 
 NS_CC_END
 
+// end of ui group
+/// @}
+
 #endif /* defined(__CocoGUI__Label__) */