[Dialogs] Document icon image scaling condition

Update Dialogs API documentation to indicate when `titleIcon` is scaled.

PiperOrigin-RevId: 309395216

components/Dialogs/src/MDCAlertController+Customize.h

@@ -24,11 +24,11 @@
 /**
  An optional custom view above the title of the alert.
 
- @discussion Use `titleIcon` to display icons or images.  Use `titleIconView` for custom views
-             implementations. If both `titleIcon` and `titleIconView` are set, 'titleIcon' is
-             ignored.
+ @note Use `titleIcon` to display icons or images.  Use `titleIconView` for custom views
+       implementations. If both `titleIcon` and `titleIconView` are set, 'titleIcon' is ignored.
 
- @discussion Custom title views are aligned with the title and may be resized to fit.
+ @note Custom title views are aligned based on `titleIconAlignment` value, and are not automatically
+       resized to fit the available space.
  */
 @property(nonatomic, strong, nullable) UIView *titleIconView;
 
@@ -37,9 +37,12 @@
  'titleIconImageView' to fine tune the appearance of `titleIcon` when necessary, for instance, to
  set its `contentMode`.
 
- @discussion Use `titleIcon` to display icons or images.  Use `titleIconView` for custom views
-             implementations. If both `titleIcon` and `titleIconView` are set, 'titleIcon' (and
-             `titleIconImageView`) are ignored.
+ @note Use `titleIcon` to display icons or images.  Use `titleIconView` for custom views
+       implementations. If both `titleIcon` and `titleIconView` are set, 'titleIcon' (and
+       `titleIconImageView`) are ignored.
+
+ @note: To proportionally scale large images to fit the available space, set
+        `titleIconAlignment` to `MDCContentHorizontalAlignmentJustified`.
  */
 @property(nonatomic, nullable, strong, readonly) UIImageView *titleIconImageView;
 

components/Dialogs/src/MDCAlertController.h

@@ -92,7 +92,12 @@
 /** The alignment applied to the title of the Alert. Defaults to @c NSTextAlignmentNatural. */
 @property(nonatomic, assign) NSTextAlignment titleAlignment;
 
-/** An optional icon appearing above the title of the Alert Controller.*/
+/**
+ An (optional) icon or image that appears above the title of the Alert Controller.
+
+ @note: To proportionally scale large images to fit the available space, set
+        `titleIconAlignment` to `MDCContentHorizontalAlignmentJustified`.
+ */
 @property(nonatomic, strong, nullable) UIImage *titleIcon;
 
 /** The tint color applied to the titleIcon. Leave empty to preserve original image color(s).*/
@@ -104,7 +109,10 @@
  To preserve backward compatibility, the default alignment of the title icon matches the alignment
  of the title, set by @c titleAlignment. The @c titleIconAlignment value will automatically match
  @c titleAlignment until the value of @c titleIconAlignment is first set.
- */
+
+ @note: Large `titleIcon` images will be proportionally scaled to fit the available space when
+        `titleIconAlignment` is set to `MDCContentHorizontalAlignmentJustified`.
+*/
 @property(nonatomic, assign) NSTextAlignment titleIconAlignment;
 
 /** The font applied to the message of Alert Controller.*/