Merge pull request #16077 from mogemimi/fix-documentation-comments

Fix documentation when compile with -Wdocumentation and Clang

cocos/2d/CCLight.h

@@ -245,7 +245,7 @@ public:
      *
      * @param outerAngle The angle of spot light (in radians).
      */
-    void setOuterAngle(float angle);
+    void setOuterAngle(float outerAngle);
     
     /**
      * Returns the outer angle of the spot light (in radians).

cocos/3d/CCSkeleton3D.h

@@ -68,8 +68,8 @@ public:
      * @param trans translate vec3
      * @param rot   rotation quaternion
      * @param scale scale vec3
-     * @param tag, unique tag, only blend animation between different tags
+     * @param tag unique tag, only blend animation between different tags
-     * @param weight, blend weight
+     * @param weight blend weight
      */
     void setAnimationValue(float* trans, float* rot, float* scale, void* tag = nullptr, float weight = 1.0f);
     

cocos/base/CCData.h

@@ -128,16 +128,14 @@ public:
      * The data object is set to empty state, that is internal buffer is set to nullptr
      * and size is set to zero.
      * Usage:
-     *  <pre>
+     * @code
-     *  {@code
      *  Data d;
      *  // ...
      *  ssize_t size;
      *  unsigned char* buffer = d.takeBuffer(&size);
      *  // use buffer and size
      *  free(buffer);
-     *  }
+     * @endcode
-     * </pre
      *
      * @param size Will fill with the data buffer size in bytes, if you do not care buffer size, pass nullptr.
      * @return the internal data buffer, free it after use.

cocos/base/CCNinePatchImageParser.h

@@ -76,8 +76,6 @@ public:
      * @param image A Image object pointer.
      * @param frameRect The sprite frame rect in the image atlas.
      * @param rotated Whether is sprite frame is rotated in the image atlas.
-     *
-     * @return
      */
     NinePatchImageParser(Image* image, const Rect& frameRect, bool rotated);
 

cocos/base/ccTypes.h

@@ -411,7 +411,7 @@ struct CC_DLL BlendFunc
     }
 };
 
-/** @struct TextVAlignment
+/** @enum TextVAlignment
  * Vertical text alignment type.
  *
  * @note If any of these enums are edited and/or reordered, update Texture2D.m.
@@ -423,7 +423,7 @@ enum class CC_DLL TextVAlignment
     BOTTOM
 };
 
-/** @struct TextHAlignment
+/** @enum TextHAlignment
  * Horizontal text alignment type.
  *
  * @note If any of these enums are edited and/or reordered, update Texture2D.m.

cocos/platform/CCFileUtils.h

@@ -191,8 +191,7 @@ public:
      *
      *  The template version of can accept cocos2d::Data, std::basic_string and std::vector.
      *
-     *  <pre>
+     *  @code
-     *  {@code
      *  std::string sbuf;
      *  FileUtils::getInstance()->getContents("path/to/file", &sbuf);
      *
@@ -201,8 +200,7 @@ public:
      *
      *  Data dbuf;
      *  FileUtils::getInstance()->getContents("path/to/file", &dbuf);
-     *  }
+     *  @endcode
-     * </pre
      *
      *  Note: if you read to std::vector<T> and std::basic_string<T> where T is not 8 bit type,
      *  you may get 0 ~ sizeof(T)-1 bytes padding.
@@ -210,8 +208,7 @@ public:
      *  - To write a new buffer class works with getContents, just extend ResizableBuffer.
      *  - To write a adapter for existing class, write a specialized ResizableBufferAdapter for that class, see follow code.
      *
-     *  <pre>
+     *  @code
-     *  {@code
      *  NS_CC_BEGIN // ResizableBufferAdapter needed in cocos2d namespace.
      *  template<>
      *  class ResizableBufferAdapter<AlreadyExistsBuffer> : public ResizableBuffer {
@@ -227,8 +224,7 @@ public:
      *      }
      *  };
      *  NS_CC_END
-     *  }
+     *  @endcode
-     * </pre
      *
      *  @param[in]  filename The resource file name which contains the path.
      *  @param[out] buffer The buffer where the file contents are store to.

cocos/ui/UIListView.h

@@ -232,7 +232,7 @@ public:
     /**
      * Set the margin between each item in ListView.
      *
-     * @param margin
+     * @param margin A margin in float.
      */
     void setItemsMargin(float margin);
     

cocos/ui/UIRichText.h

@@ -134,7 +134,7 @@ public:
      * @param text Content string.
      * @param fontName Content font name.
      * @param fontSize Content font size.
-     * @param flags: italics, bold, underline, strikethrough, url, outline, shadow or glow
+     * @param flags italics, bold, underline, strikethrough, url, outline, shadow or glow
      * @param url uniform resource locator
      * @param outlineColor the color of the outline
      * @param outlineSize the outline effect size value
@@ -159,7 +159,7 @@ public:
      * @param text Content string.
      * @param fontName Content font name.
      * @param fontSize Content font size.
-     * @param flags: italics, bold, underline, strikethrough, url, outline, shadow or glow
+     * @param flags italics, bold, underline, strikethrough, url, outline, shadow or glow
      * @param url uniform resource locator
      * @param outlineColor the color of the outline
      * @param outlineSize the outline effect size value

cocos/ui/UITabControl.h

@@ -215,39 +215,39 @@ namespace ui {
         
         /**
          * remove the tab from this TabControl
-         * @param index: the index of tab
+         * @param index The index of tab
          */
         void      removeTab(int index);
         
         /**
          * set tab selected, switch the current selected tab and visible container
-         * @param index: the index of tab
+         * @param index The index of tab
          */
         void      setSelectTab(int index);
         
         /**
          * set tab selected, switch the current selected tab and visible container
-         * @param tabHeader, the tab instance
+         * @param tabHeader The tab instance
          */
         void      setSelectTab(TabHeader* tabHeader);
         
         /**
          * get TabHeader
-         * @param index, the index of tab
+         * @param index The index of tab
          */
         TabHeader* getTabHeader(int index) const;
         
         /**
          * get Container
-         * @param index, the index of tab
+         * @param index The index of tab
          */
         Layout*   getTabContainer(int index) const;
         
         /**
          * insert tab, and init the position of header and container
-         * @param index, the index tab should be
+         * @param index The index tab should be
-         * @param header, the header Button, will be a protected child in TabControl
+         * @param header The header Button, will be a protected child in TabControl
-         * @param the container, will be a protected child in TabControl
+         * @param container The container, will be a protected child in TabControl
          */
         void      insertTab(int index, TabHeader* header, Layout* container);
         
@@ -265,7 +265,7 @@ namespace ui {
 
         /**
         * get the index of tabCell in TabView, return -1 if not exists in.
-        / @return the index of tabCell in TabView,  `-1` means not exists in.
+        * @return the index of tabCell in TabView, `-1` means not exists in.
         */
         int indexOfTabHeader(const TabHeader* tabCell) const;
 
@@ -318,7 +318,7 @@ namespace ui {
 
         /**
         * set the delta zoom of selected tab
-        * @param zoom, the delta zoom
+        * @param zoom The delta zoom
         */
         void  setHeaderSelectedZoom(float zoom);
 
@@ -330,7 +330,7 @@ namespace ui {
 
         /**
         * the header dock place of header in TabControl
-        * @param: dockPlace, the strip place
+        * @param dockPlace The strip place
         */
         void         setHeaderDockPlace(TabControl::Dock dockPlace);
         TabControl::Dock getHeaderDockPlace() const { return _headerDockPlace; }

cocos/ui/UIWidget.h

@@ -729,7 +729,6 @@ public:
     /**
      * Toggle widget focus status.
      *@param focus  pass true to let the widget get focus or pass false to let the widget lose focus
-     *@return void
      */
     void setFocused(bool focus);
     
@@ -742,7 +741,6 @@ public:
     /**
      * Allow widget to accept focus.
      *@param enable pass true/false to enable/disable the focus ability of a widget
-     *@return void
      */
     void setFocusEnabled(bool enable);
     
@@ -798,7 +796,6 @@ public:
     /**
      *Toggle use unify size.
      *@param enable True to use unify size, false otherwise.
-     *@return void
      */
     void setUnifySizeEnabled(bool enable);
 
@@ -836,7 +833,6 @@ public:
     /**
      * Toggle layout component enable.
      *@param enable Layout Component of a widget
-     *@return void
      */
     void setLayoutComponentEnabled(bool enable);
 
@@ -870,7 +866,6 @@ CC_CONSTRUCTOR_ACCESS:
      * This method is called when a focus change event happens
      *@param widgetLostFocus  The widget which lose its focus
      *@param widgetGetFocus  The widget which get its focus
-     *@return void
      */
     void onFocusChange(Widget* widgetLostFocus, Widget* widgetGetFocus);
     
@@ -878,7 +873,6 @@ CC_CONSTRUCTOR_ACCESS:
      * Dispatch a EventFocus through a EventDispatcher
      *@param widgetLoseFocus  The widget which lose its focus
      *@param widgetGetFocus he widget which get its focus
-     *@return void
      */
     void  dispatchFocusEvent(Widget* widgetLoseFocus, Widget* widgetGetFocus);