From fd058f612170badf66856671731613705ea4c21a Mon Sep 17 00:00:00 2001
From: wilsonshih <wilsonshih@google.com>
Date: Wed, 13 Feb 2019 15:57:06 +0800
Subject: [PATCH] Add API comment for new API in WallpaperService.

Supplement some comment to let developer know how to use new API
WallpaperInfo#supportsMultipleDisplays.

Also add a nullability annotation and comment for
WallpaperService.Engine#getDisplayContext.

Fix: 124302009
Fix: 123661589
Test: Build pass and read comment.

Change-Id: Id6040eff12495838f21f539b7c68d6743c9baf74
---
 api/current.txt                                           | 2 +-
 core/java/android/app/WallpaperInfo.java                  | 7 +++++++
 core/java/android/service/wallpaper/WallpaperService.java | 4 ++++
 core/res/res/values/attrs.xml                             | 3 ++-
 4 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/api/current.txt b/api/current.txt
index 1c60efa62be37..efa82e8b07344 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -42136,7 +42136,7 @@ package android.service.wallpaper {
     method protected void dump(String, java.io.FileDescriptor, java.io.PrintWriter, String[]);
     method public int getDesiredMinimumHeight();
     method public int getDesiredMinimumWidth();
-    method public android.content.Context getDisplayContext();
+    method @Nullable public android.content.Context getDisplayContext();
     method public android.view.SurfaceHolder getSurfaceHolder();
     method public boolean isPreview();
     method public boolean isVisible();
diff --git a/core/java/android/app/WallpaperInfo.java b/core/java/android/app/WallpaperInfo.java
index f0f7d899ff073..28c79aadf84e5 100644
--- a/core/java/android/app/WallpaperInfo.java
+++ b/core/java/android/app/WallpaperInfo.java
@@ -371,10 +371,17 @@ public final class WallpaperInfo implements Parcelable {
      * Returns whether this wallpaper service can support multiple engines to render on each surface
      * independently. An example use case is a multi-display set-up where the wallpaper service can
      * render surfaces to each of the connected displays.
+     * <p>
+     * This corresponds to the value {@link android.R.styleable#Wallpaper_supportsMultipleDisplays}
+     * in the XML description of the wallpaper.
+     * <p>
+     * The default value is {@code false}.
      *
      * @see WallpaperService#onCreateEngine()
      * @see WallpaperService.Engine#onCreate(SurfaceHolder)
      * @return {@code true} if multiple engines can render independently on each surface.
+     *
+     * @attr ref android.R.styleable#Wallpaper_supportsMultipleDisplays
      */
     public boolean supportsMultipleDisplays() {
         return mSupportMultipleDisplays;
diff --git a/core/java/android/service/wallpaper/WallpaperService.java b/core/java/android/service/wallpaper/WallpaperService.java
index b197c8a8a3880..c042a8c8ae1c5 100644
--- a/core/java/android/service/wallpaper/WallpaperService.java
+++ b/core/java/android/service/wallpaper/WallpaperService.java
@@ -1068,9 +1068,13 @@ public abstract class WallpaperService extends Service {
          * For multiple display environment, multiple engines can be created to render on each
          * display, but these displays may have different densities. Use this context to get the
          * corresponding resources for currently display, avoiding the context of the service.
+         * <p>
+         * The display context will never be {@code null} after
+         * {@link Engine#onCreate(SurfaceHolder)} has been called.
          *
          * @return A {@link Context} for current display.
          */
+        @Nullable
         public Context getDisplayContext() {
             return mDisplayContext;
         }
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 224f54c64b633..088669da7b913 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -8004,7 +8004,8 @@
 
         <!-- Indicates that this wallpaper service can support multiple engines to render on each
              surface independently. An example use case is a multi-display set-up where the
-             wallpaper service can render surfaces to each of the connected displays. -->
+             wallpaper service can render surfaces to each of the connected displays. Corresponds to
+             {@link android.app.WallpaperInfo#supportsMultipleDisplays()} -->
         <attr name="supportsMultipleDisplays" format="boolean" />
 
     </declare-styleable>