diff --git a/core/java/android/view/Display.java b/core/java/android/view/Display.java
index 9cb0d1ff2c3f4..a06b0e0355d8e 100644
--- a/core/java/android/view/Display.java
+++ b/core/java/android/view/Display.java
@@ -741,35 +741,42 @@ public final class Display {
     }
 
     /**
-     * Gets the size of the display, in pixels.
-     * Value returned by this method does not necessarily represent the actual raw size
-     * (native resolution) of the display.
-     * <p>
-     * 1. The returned size may be adjusted to exclude certain system decor elements
-     * that are always visible.
-     * </p><p>
-     * 2. It may be scaled to provide compatibility with older applications that
-     * were originally designed for smaller displays.
-     * </p><p>
-     * 3. It can be different depending on the WindowManager to which the display belongs.
-     * </p><p>
-     * - If requested from non-Activity context (e.g. Application context via
-     * {@code (WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE)})
-     * it will report the size of the entire display based on current rotation and with subtracted
-     * system decoration areas.
-     * </p><p>
-     * - If requested from activity (either using {@code getWindowManager()} or
-     * {@code (WindowManager) getSystemService(Context.WINDOW_SERVICE)}) resulting size will
-     * correspond to current app window size. In this case it can be smaller than physical size in
-     * multi-window mode.
-     * </p><p>
-     * Typically for the purposes of layout apps should make a request from activity context
-     * to obtain size available for the app content.
-     * </p>
+     * Gets the size of the display in pixels.
      *
-     * @param outSize A {@link Point} object to receive the size information.
-     * @deprecated Use {@link WindowManager#getCurrentWindowMetrics()} to obtain an instance of
-     * {@link WindowMetrics} and use {@link WindowMetrics#getBounds()} instead.
+     * <p>The return value does not necessarily represent the actual size (native resolution) of the
+     * display. The returned size might be adjusted to exclude certain system decor elements that
+     * are always visible, or the size might be scaled to provide compatibility with older
+     * applications that were originally designed for smaller displays.
+     *
+     * <p>The returned size can also be different depending on the WindowManager bound to the
+     * display:
+     * <ul>
+     *     <li>If size is requested from an activity (either using a WindowManager accessed by
+     *         {@code getWindowManager()} or {@code getSystemService(Context.WINDOW_SERVICE)}), the
+     *         size of the current app window is returned. As a result, in multi-window mode, the
+     *         returned size can be smaller than the size of the device screen.
+     *     <li>If size is requested from a non-activity context (for example, the application
+     *         context, where the WindowManager is accessed by
+     *         {@code getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}), the
+     *         returned size can vary depending on API level:
+     *         <ul>
+     *             <li>API level 29 and below &mdash; The size of the entire display (based on
+     *                 current rotation) minus system decoration areas is returned.
+     *             <li>API level 30 and above &mdash; The size of the top running activity in the
+     *                 current process is returned. If the current process has no running
+     *                 activities, the size of the device default display, including system
+     *                 decoration areas, is returned.
+     *         </ul>
+     * </ul>
+     *
+     * <p>For layout purposes, apps should make a request from an activity context to obtain the
+     * size of the display area available for app content.
+     *
+     * @param outSize A {@link Point} object which receives the display size information.
+     *
+     * @deprecated Use {@link WindowMetrics} instead. Obtain a {@code WindowMetrics} instance by
+     *     calling {@link WindowManager#getCurrentWindowMetrics()}, then call
+     *     {@link WindowMetrics#getBounds()} to get the dimensions of the application window.
      */
     @Deprecated
     public void getSize(Point outSize) {
@@ -785,8 +792,9 @@ public final class Display {
      * Gets the size of the display as a rectangle, in pixels.
      *
      * @param outSize A {@link Rect} object to receive the size information.
+     *
      * @deprecated Use {@link WindowMetrics#getBounds()} to get the dimensions of the application
-     * window area.
+     * window.
      */
     @Deprecated
     public void getRectSize(Rect outSize) {
@@ -1275,32 +1283,39 @@ public final class Display {
     }
 
     /**
-     * Gets display metrics that describe the size and density of this display.
-     * The size returned by this method does not necessarily represent the
-     * actual raw size (native resolution) of the display.
-     * <p>
-     * 1. The returned size may be adjusted to exclude certain system decor elements
-     * that are always visible.
-     * </p><p>
-     * 2. It may be scaled to provide compatibility with older applications that
-     * were originally designed for smaller displays.
-     * </p><p>
-     * 3. It can be different depending on the WindowManager to which the display belongs.
-     * </p><p>
-     * - If requested from non-Activity context (e.g. Application context via
-     * {@code (WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE)})
-     * metrics will report the size of the entire display based on current rotation and with
-     * subtracted system decoration areas.
-     * </p><p>
-     * - If requested from activity (either using {@code getWindowManager()} or
-     * {@code (WindowManager) getSystemService(Context.WINDOW_SERVICE)}) resulting metrics will
-     * correspond to current app window metrics. In this case the size can be smaller than physical
-     * size in multi-window mode.
-     * </p>
+     * Gets the size and density of this display.
+     *
+     * <p>The size returned does not necessarily represent the actual size (native resolution) of
+     * the display. The returned size might be adjusted to exclude certain system decor elements
+     * that are always visible, or the size might be scaled to provide compatibility with older
+     * applications that were originally designed for smaller displays.
+     *
+     * <p>The returned size can also be different depending on the WindowManager associated with the
+     * display:
+     * <ul>
+     *     <li>If metrics are requested from an activity (either using a WindowManager accessed by
+     *         {@code getWindowManager()} or {@code getSystemService(Context.WINDOW_SERVICE)}), the
+     *         returned metrics provide the size of the current app window. As a result, in
+     *         multi-window mode, the returned size can be smaller than the size of the device
+     *         screen.
+     *     <li>If metrics are requested from a non-activity context (for example, the application
+     *         context, where the WindowManager is accessed by
+     *         {@code getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}), the
+     *         returned size can vary depending on API level:
+     *         <ul>
+     *             <li>API level 29 and below &mdash; The returned metrics provide the size of the
+     *                 entire display (based on current rotation) minus system decoration areas.
+     *             <li>API level 30 and above &mdash; The returned metrics provide the size of the
+     *                 top running activity in the current process. If the current process has no
+     *                 running activities, the metrics provide the size of the default display of
+     *                 the device, including system decoration areas.
+     *         </ul>
+     * </ul>
+     *
+     * @param outMetrics A {@link DisplayMetrics} object which receives the display metrics.
      *
-     * @param outMetrics A {@link DisplayMetrics} object to receive the metrics.
      * @deprecated Use {@link WindowMetrics#getBounds()} to get the dimensions of the application
-     * window area, and {@link Configuration#densityDpi} to get the current density.
+     *     window. Use {@link Configuration#densityDpi} to get the display density.
      */
     @Deprecated
     public void getMetrics(DisplayMetrics outMetrics) {