DisplayCutout: Fix attrs.xml javadoc

Fixes an issue with the javadoc for windowLayoutInDisplayCutoutMode.
Removes @tags from enum javadocs, because they get merged into a table,
which does not support inner @tags. Instead, use <code> tags which work
in that context.

Also replaces @see tags with {@link} tags in the attr javadoc, because
the enum value table gets appended, but it is invalid to have text after
an @see tag.

Change-Id: Ib97e9aa82e173d99a467132a0d403793d7297e61
Fixes: 76448223
Test: make doc-comment-check-docs, verify output at $ANDROID_BUILD_TOP/out/target/common/docs/doc-comment-check/reference/android/R.attr.html#windowLayoutInDisplayCutoutMode

diff --git a/core/java/android/view/WindowManager.java b/core/java/android/view/WindowManager.java
index abc19d0..8c568bc 100644 (file)
--- a/core/java/android/view/WindowManager.java
+++ b/core/java/android/view/WindowManager.java
@@ -2220,7 +2220,7 @@ public interface WindowManager extends ViewManager {
         @IntDef(
                 flag = true,
                 value = {LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT,
-                        LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS,
+                        LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES,
                         LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER})
         @interface LayoutInDisplayCutoutMode {}
 
@@ -2231,10 +2231,11 @@ public interface WindowManager extends ViewManager {
          * Defaults to {@link #LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT}.
          *
          * @see #LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT
-         * @see #LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS
+         * @see #LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
          * @see #LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
          * @see DisplayCutout
-         * @see android.R.attr#layoutInDisplayCutoutMode
+         * @see android.R.attr#windowLayoutInDisplayCutoutMode
+         *         android:windowLayoutInDisplayCutoutMode
          */
         @LayoutInDisplayCutoutMode
         public int layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT;
@@ -2245,10 +2246,10 @@ public interface WindowManager extends ViewManager {
          * laid out such that it does not overlap with the {@link DisplayCutout} area.
          *
          * <p>
-         * In practice, this means that if the window did not set FLAG_FULLSCREEN or
-         * SYSTEM_UI_FLAG_FULLSCREEN, it can extend into the cutout area in portrait if the cutout
-         * is at the top edge. Similarly for SYSTEM_UI_FLAG_HIDE_NAVIGATION and a cutout at the
-         * bottom of the screen.
+         * In practice, this means that if the window did not set {@link #FLAG_FULLSCREEN} or
+         * {@link View#SYSTEM_UI_FLAG_FULLSCREEN}, it can extend into the cutout area in portrait
+         * if the cutout is at the top edge. Similarly for
+         * {@link View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} and a cutout at the bottom of the screen.
          * Otherwise (i.e. fullscreen or landscape) it is laid out such that it does not overlap the
          * cutout area.
          *
@@ -2258,6 +2259,9 @@ public interface WindowManager extends ViewManager {
          *
          * @see DisplayCutout
          * @see WindowInsets
+         * @see #layoutInDisplayCutoutMode
+         * @see android.R.attr#windowLayoutInDisplayCutoutMode
+         *         android:windowLayoutInDisplayCutoutMode
          */
         public static final int LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT = 0;
 
@@ -2281,6 +2285,9 @@ public interface WindowManager extends ViewManager {
          *
          * @see DisplayCutout
          * @see WindowInsets#getDisplayCutout()
+         * @see #layoutInDisplayCutoutMode
+         * @see android.R.attr#windowLayoutInDisplayCutoutMode
+         *         android:windowLayoutInDisplayCutoutMode
          */
         public static final int LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES = 1;
 
@@ -2288,12 +2295,14 @@ public interface WindowManager extends ViewManager {
          * The window is never allowed to overlap with the DisplayCutout area.
          *
          * <p>
-         * This should be used with windows that transiently set SYSTEM_UI_FLAG_FULLSCREEN to
-         * avoid a relayout of the window when the flag is set or cleared.
+         * This should be used with windows that transiently set
+         * {@link View#SYSTEM_UI_FLAG_FULLSCREEN} or {@link View#SYSTEM_UI_FLAG_HIDE_NAVIGATION}
+         * to avoid a relayout of the window when the respective flag is set or cleared.
          *
          * @see DisplayCutout
-         * @see View#SYSTEM_UI_FLAG_FULLSCREEN SYSTEM_UI_FLAG_FULLSCREEN
-         * @see View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
+         * @see #layoutInDisplayCutoutMode
+         * @see android.R.attr#windowLayoutInDisplayCutoutMode
+         *         android:windowLayoutInDisplayCutoutMode
          */
         public static final int LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER = 2;
 

diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 3135455..aceba08 100644 (file)
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -2123,44 +2123,48 @@
         <!-- Controls how the window is laid out if there is a {@code DisplayCutout}.
         <p>
         Defaults to {@code default}.
-
-        @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT
-        @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
-        @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
-        @see android.view.DisplayCutout
-        @see android.R.attr#layoutInDisplayCutoutMode -->
+        <p>
+        See also
+        {@link android.view.WindowManager.LayoutParams#layoutInDisplayCutoutMode
+                WindowManager.LayoutParams.layoutInDisplayCutoutMode},
+        {@link android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT},
+        {@link android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES},
+        {@link android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER},
+        and {@link android.view.DisplayCutout DisplayCutout}
+        -->
         <attr name="windowLayoutInDisplayCutoutMode">
-            <!-- The window is allowed to extend into the {@code DisplayCutout} area, only if the
-            {@code DisplayCutout} is fully contained within a system bar. Otherwise, the window is
-            laid out such that it does not overlap with the {@code DisplayCutout} area.
-
-            @see android.view.DisplayCutout
-            @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT
+            <!-- <p>
+            The window is allowed to extend into the <code>DisplayCutout</code> area, only if
+            the <code>DisplayCutout</code> is fully contained within a system bar. Otherwise, the
+            window is laid out such that it does not overlap with the <code>DisplayCutout</code>
+            area.
+            <p>
+            Corresponds to <code>LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT</code>.
             -->
             <enum name="default" value="0" />
-            <!--
-            The window is always allowed to extend into the {@code DisplayCutout} areas on the short
-            edges of the screen even if fullscreen or in landscape.
-            The window will never extend into a {@link DisplayCutout} area on the long edges of the
-            screen.
+            <!-- <p>
+            The window is always allowed to extend into the <code>DisplayCutout</code> areas on the
+            short edges of the screen even if fullscreen or in landscape.
+            The window will never extend into a <code>DisplayCutout</code> area on the long edges of
+            the screen.
             <p>
             The window must make sure that no important content overlaps with the
-            {@link DisplayCutout}.
-
-            @see android.view.DisplayCutout
-            @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
+            <code>DisplayCutout</code>.
+            <p>
+            Corresponds to <code>LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES</code>.
             -->
             <enum name="shortEdges" value="1" />
-            <!-- Use {@code shortEdges} instead. This is temporarily here to unblock pushing the SDK
-                 until all usages have been migrated to {@code shortEdges} -->
+            <!-- Use <code>shortEdges</code> instead. This is temporarily here to unblock pushing
+                 the SDK until all usages have been migrated to <code>shortEdges</code> -->
             <enum name="always" value="1" />
-            <!-- The window is never allowed to overlap with the DisplayCutout area.
+            <!-- <p>
+            The window is never allowed to overlap with the <code>DisplayCutout</code> area.
             <p>
-            This should be used with windows that transiently set {@code SYSTEM_UI_FLAG_FULLSCREEN}
-            to avoid a relayout of the window when the flag is set or cleared.
-
-            @see android.view.DisplayCutout
-            @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
+            This should be used with windows that transiently set
+            <code>SYSTEM_UI_FLAG_FULLSCREEN</code> to avoid a relayout of the window when the
+            flag is set or cleared.
+            <p>
+            Corresponds to <code>LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER</code>.
             -->
             <enum name="never" value="2" />
         </attr>