Add comprehensive KDoc documentation to BackgroundStyleApplicator (#54346)

Summary:
Pull Request resolved: #54346

Added comprehensive KDoc documentation to the BackgroundStyleApplicator class and all 25 public methods covering backgrounds, borders, outlines, and box shadows.

changelog: [internal] internal

Reviewed By: lenaic

Differential Revision: D85926890

fbshipit-source-id: 5a398bf8d57d6b6dff6b012ac225bc96d56e2573

Author: mdvacca

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/BackgroundStyleApplicator.kt

@@ -45,12 +45,22 @@ import com.facebook.react.uimanager.style.LogicalEdge
 import com.facebook.react.uimanager.style.OutlineStyle
 
 /**
- * BackgroundStyleApplicator is responsible for applying backgrounds, borders, and related effects,
- * to an Android view
+ * Utility object responsible for applying backgrounds, borders, and related visual effects to
+ * Android views.
+ *
+ * This object provides methods to manage background colors, images, borders, outlines, and box
+ * shadows for React Native views. It handles the complex layering and composition of these visual
+ * properties by managing [CompositeBackgroundDrawable] instances.
  */
 @OptIn(UnstableReactNativeAPI::class)
 public object BackgroundStyleApplicator {
 
+  /**
+   * Sets the background color of the view.
+   *
+   * @param view The view to apply the background color to
+   * @param color The color to set, or null to remove the background color
+   */
   @JvmStatic
   public fun setBackgroundColor(view: View, @ColorInt color: Int?): Unit {
     // No color to set, and no color already set
@@ -64,6 +74,12 @@ public object BackgroundStyleApplicator {
     ensureBackgroundDrawable(view).backgroundColor = color ?: Color.TRANSPARENT
   }
 
+  /**
+   * Sets the background image layers for the view.
+   *
+   * @param view The view to apply the background images to
+   * @param backgroundImageLayers The list of background image layers to apply, or null to remove
+   */
   @JvmStatic
   public fun setBackgroundImage(
       view: View,
@@ -90,12 +106,25 @@ public object BackgroundStyleApplicator {
     ensureBackgroundImageDrawable(view).backgroundRepeat = backgroundRepeats
   }
 
+  /**
+   * Gets the background color of the view.
+   *
+   * @param view The view to get the background color from
+   * @return The background color, or null if no background color is set
+   */
   @JvmStatic
   @ColorInt
   public fun getBackgroundColor(view: View): Int? {
     return getBackground(view)?.backgroundColor
   }
 
+  /**
+   * Sets the border width for a specific edge of the view.
+   *
+   * @param view The view to apply the border width to
+   * @param edge The logical edge (start, end, top, bottom, etc.) to set the width for
+   * @param width The border width in DIPs, or null to remove
+   */
   @JvmStatic
   public fun setBorderWidth(view: View, edge: LogicalEdge, width: Float?): Unit {
     val composite = ensureCompositeBackgroundDrawable(view)
@@ -121,6 +150,13 @@ public object BackgroundStyleApplicator {
     }
   }
 
+  /**
+   * Gets the border width for a specific edge of the view.
+   *
+   * @param view The view to get the border width from
+   * @param edge The logical edge to get the width for
+   * @return The border width in DIPs, or null if not set
+   */
   @JvmStatic
   public fun getBorderWidth(view: View, edge: LogicalEdge): Float? {
     val width = getBorder(view)?.borderWidth?.getRaw(edge.toSpacingType())
@@ -131,17 +167,38 @@ public object BackgroundStyleApplicator {
     }
   }
 
+  /**
+   * Sets the border color for a specific edge of the view.
+   *
+   * @param view The view to apply the border color to
+   * @param edge The logical edge to set the color for
+   * @param color The border color, or null to remove
+   */
   @JvmStatic
   public fun setBorderColor(view: View, edge: LogicalEdge, @ColorInt color: Int?): Unit {
     ensureBorderDrawable(view).setBorderColor(edge, color)
   }
 
+  /**
+   * Gets the border color for a specific edge of the view.
+   *
+   * @param view The view to get the border color from
+   * @param edge The logical edge to get the color for
+   * @return The border color, or null if not set
+   */
   @JvmStatic
   @ColorInt
   public fun getBorderColor(view: View, edge: LogicalEdge): Int? {
     return getBorder(view)?.getBorderColor(edge)
   }
 
+  /**
+   * Sets the border radius for a specific corner of the view.
+   *
+   * @param view The view to apply the border radius to
+   * @param corner The corner property to set the radius for
+   * @param radius The border radius value (length or percentage), or null to remove
+   */
   @JvmStatic
   public fun setBorderRadius(
       view: View,
@@ -183,22 +240,47 @@ public object BackgroundStyleApplicator {
     compositeBackgroundDrawable.invalidateSelf()
   }
 
+  /**
+   * Gets the border radius for a specific corner of the view.
+   *
+   * @param view The view to get the border radius from
+   * @param corner The corner property to get the radius for
+   * @return The border radius value, or null if not set
+   */
   @JvmStatic
   public fun getBorderRadius(view: View, corner: BorderRadiusProp): LengthPercentage? {
 
     return getCompositeBackgroundDrawable(view)?.borderRadius?.get(corner)
   }
 
+  /**
+   * Sets the border style for the view.
+   *
+   * @param view The view to apply the border style to
+   * @param borderStyle The border style (solid, dashed, dotted), or null to remove
+   */
   @JvmStatic
   public fun setBorderStyle(view: View, borderStyle: BorderStyle?) {
     ensureBorderDrawable(view).borderStyle = borderStyle
   }
 
+  /**
+   * Gets the border style of the view.
+   *
+   * @param view The view to get the border style from
+   * @return The border style, or null if not set
+   */
   @JvmStatic
   public fun getBorderStyle(view: View): BorderStyle? {
     return getBorder(view)?.borderStyle
   }
 
+  /**
+   * Sets the outline color for the view (Fabric only).
+   *
+   * @param view The view to apply the outline color to
+   * @param outlineColor The outline color, or null to remove
+   */
   @JvmStatic
   public fun setOutlineColor(view: View, @ColorInt outlineColor: Int?) {
     if (ViewUtil.getUIManagerType(view) != UIManagerType.FABRIC) {
@@ -211,8 +293,20 @@ public object BackgroundStyleApplicator {
     }
   }
 
+  /**
+   * Gets the outline color of the view.
+   *
+   * @param view The view to get the outline color from
+   * @return The outline color, or null if not set
+   */
   @JvmStatic public fun getOutlineColor(view: View): Int? = getOutlineDrawable(view)?.outlineColor
 
+  /**
+   * Sets the outline offset for the view (Fabric only).
+   *
+   * @param view The view to apply the outline offset to
+   * @param outlineOffset The outline offset in DIPs
+   */
   @JvmStatic
   public fun setOutlineOffset(view: View, outlineOffset: Float): Unit {
     if (ViewUtil.getUIManagerType(view) != UIManagerType.FABRIC) {
@@ -223,8 +317,20 @@ public object BackgroundStyleApplicator {
     outline.outlineOffset = outlineOffset.dpToPx()
   }
 
+  /**
+   * Gets the outline offset of the view.
+   *
+   * @param view The view to get the outline offset from
+   * @return The outline offset in pixels, or null if not set
+   */
   public fun getOutlineOffset(view: View): Float? = getOutlineDrawable(view)?.outlineOffset
 
+  /**
+   * Sets the outline style for the view (Fabric only).
+   *
+   * @param view The view to apply the outline style to
+   * @param outlineStyle The outline style (solid, dashed, dotted), or null to remove
+   */
   @JvmStatic
   public fun setOutlineStyle(view: View, outlineStyle: OutlineStyle?): Unit {
     if (ViewUtil.getUIManagerType(view) != UIManagerType.FABRIC) {
@@ -237,8 +343,20 @@ public object BackgroundStyleApplicator {
     }
   }
 
+  /**
+   * Gets the outline style of the view.
+   *
+   * @param view The view to get the outline style from
+   * @return The outline style, or null if not set
+   */
   public fun getOutlineStyle(view: View): OutlineStyle? = getOutlineDrawable(view)?.outlineStyle
 
+  /**
+   * Sets the outline width for the view (Fabric only).
+   *
+   * @param view The view to apply the outline width to
+   * @param width The outline width in DIPs
+   */
   @JvmStatic
   public fun setOutlineWidth(view: View, width: Float) {
     if (ViewUtil.getUIManagerType(view) != UIManagerType.FABRIC) {
@@ -249,8 +367,20 @@ public object BackgroundStyleApplicator {
     outline.outlineWidth = width.dpToPx()
   }
 
+  /**
+   * Gets the outline width of the view.
+   *
+   * @param view The view to get the outline width from
+   * @return The outline width in pixels, or null if not set
+   */
   public fun getOutlineWidth(view: View): Float? = getOutlineDrawable(view)?.outlineOffset
 
+  /**
+   * Sets box shadows for the view (Fabric only).
+   *
+   * @param view The view to apply box shadows to
+   * @param shadows The list of box shadow styles to apply
+   */
   @JvmStatic
   public fun setBoxShadow(view: View, shadows: List<BoxShadow>) {
     if (ViewUtil.getUIManagerType(view) != UIManagerType.FABRIC) {
@@ -309,6 +439,12 @@ public object BackgroundStyleApplicator {
             .withNewShadows(outerShadows = outerShadows, innerShadows = innerShadows)
   }
 
+  /**
+   * Sets box shadows for the view from a ReadableArray (Fabric only).
+   *
+   * @param view The view to apply box shadows to
+   * @param shadows The array of box shadow definitions, or null to remove all shadows
+   */
   @JvmStatic
   public fun setBoxShadow(view: View, shadows: ReadableArray?) {
     if (shadows == null) {
@@ -323,11 +459,26 @@ public object BackgroundStyleApplicator {
     BackgroundStyleApplicator.setBoxShadow(view, shadowStyles)
   }
 
+  /**
+   * Sets a feedback underlay drawable for the view.
+   *
+   * @param view The view to apply the feedback underlay to
+   * @param drawable The drawable to use as feedback underlay, or null to remove
+   */
   @JvmStatic
   public fun setFeedbackUnderlay(view: View, drawable: Drawable?) {
     ensureCompositeBackgroundDrawable(view).withNewFeedbackUnderlay(drawable)
   }
 
+  /**
+   * Clips the canvas to the padding box of the view.
+   *
+   * The padding box is the area within the borders of the view, accounting for border radius if
+   * present.
+   *
+   * @param view The view whose padding box defines the clipping region
+   * @param canvas The canvas to clip
+   */
   @JvmStatic
   public fun clipToPaddingBox(view: View, canvas: Canvas) {
     val drawingRect = Rect()
@@ -366,6 +517,13 @@ public object BackgroundStyleApplicator {
     }
   }
 
+  /**
+   * Resets the background styling of the view to its original state.
+   *
+   * This removes any CompositeBackgroundDrawable and restores the original background.
+   *
+   * @param view The view to reset
+   */
   @JvmStatic
   public fun reset(view: View) {
     if (view.background is CompositeBackgroundDrawable) {