From 2be8a961a97e5f580acae0c5046fef5068d2a9b7 Mon Sep 17 00:00:00 2001
From: Makoto Onuki <omakoto@google.com>
Date: Thu, 23 Feb 2023 15:19:56 -0800
Subject: [PATCH] Update the SHORT_SERVICE javadoc

Test: m offline-sdk-docs and look at the generated javadoc.

Bug: 257270313
Change-Id: I0d6d3c17bb800a230b19c9971a02fba61a7b069a
---
 core/java/android/content/pm/ServiceInfo.java | 44 +++++++++++++------
 1 file changed, 31 insertions(+), 13 deletions(-)

diff --git a/core/java/android/content/pm/ServiceInfo.java b/core/java/android/content/pm/ServiceInfo.java
index f3ad9d1488ff0..69e5ea2f59d47 100644
--- a/core/java/android/content/pm/ServiceInfo.java
+++ b/core/java/android/content/pm/ServiceInfo.java
@@ -376,8 +376,8 @@ public class ServiceInfo extends ComponentInfo
      *   <li>Headless system apps</li>
      *   <li><a href="{@docRoot}guide/topics/admin/device-admin">Device admin apps</a></li>
      *   <li>Active VPN apps</li>
-     *   <li>Apps holding {@link Manifest.permission#SCHEDULE_EXACT_ALARM} or
-     *       {@link Manifest.permission#USE_EXACT_ALARM} permission.</li>
+     *   <li>Apps holding {@link android.Manifest.permission#SCHEDULE_EXACT_ALARM} or
+     *       {@link android.Manifest.permission#USE_EXACT_ALARM} permission.</li>
      * </ul>
      * </p>
      */
@@ -393,7 +393,7 @@ public class ServiceInfo extends ComponentInfo
      *
      * <p>Unlike other foreground service types, this type is not associated with a specific use
      * case, and it will not require any special permissions
-     * (besides {@link Manifest.permission#FOREGROUND_SERVICE}).
+     * (besides {@link android.Manifest.permission#FOREGROUND_SERVICE}).
      *
      * However, this type has the following restrictions.
      *
@@ -401,19 +401,21 @@ public class ServiceInfo extends ComponentInfo
      *     <li>
      *         The type has a 3 minute timeout.
      *         A foreground service of this type must be stopped within the timeout by
-     *         {@link android.app.Service#stopSelf),
-     *         or {@link android.content.Context#stopService).
-     *         {@link android.app.Service#stopForeground) will also work, which will demote the
+     *         {@link android.app.Service#stopSelf()},
+     *         {@link android.content.Context#stopService(android.content.Intent)}
+     *         or their overloads).
+     *         {@link android.app.Service#stopForeground(int)} will also work,
+     *         which will demote the
      *         service to a "background" service, which will soon be stopped by the system.
      *
-     *         <p>The system will <em>not</em> automatically stop it.
-     *
      *         <p>If the service isn't stopped within the timeout,
-     *         {@link android.app.Service#onTimeout(int)} will be called.
+     *         {@link android.app.Service#onTimeout(int)} will be called. Note, even when the
+     *         system calls this callback, it will not stop the service automatically.
+     *         You still need to stop the service using one of the aforementioned
+     *         ways even when you get this callback.
      *
      *         <p>If the service is still not stopped after the callback,
-     *         the app will be declared an ANR after a short grace period of several seconds.
-     *
+     *         the app will be declared an ANR, after a short grace period of several seconds.
      *     <li>
      *         A foreground service of this type cannot be made "sticky"
      *         (see {@link android.app.Service#START_STICKY}). That is, if an app is killed
@@ -427,10 +429,26 @@ public class ServiceInfo extends ComponentInfo
      *         <a href="/guide/components/foreground-services#background-start-restrictions>
      *             Restrictions on background starts
      *         </a>
+     *     <li>
+     *         You can combine multiple foreground services types with {@code |}s, and you can
+     *         combine
+     *         {@link android.content.pm.ServiceInfo#FOREGROUND_SERVICE_TYPE_SHORT_SERVICE}.
+     *         with other types as well.
+     *         However,
+     *         {@link android.content.pm.ServiceInfo#FOREGROUND_SERVICE_TYPE_SHORT_SERVICE}
+     *         is for situations
+     *         where you have no other valid foreground services to use and the timeout is long
+     *         enough for the task, and if you can use other types, there's no point using
+     *         this type.
+     *         For this reason, if
+     *         {@link android.content.pm.ServiceInfo#FOREGROUND_SERVICE_TYPE_SHORT_SERVICE}
+     *         is combined with other foreground service types, the system will simply ignore
+     *         it, and as a result,
+     *         none of the above restrictions will apply (e.g. there'll be no timeout).
      * </ul>
      *
-     * <p>Note, even though
-     * {@link ServiceInfo#FOREGROUND_SERVICE_TYPE_SHORT_SERVICE}
+     * <p>Also note, even though
+     * {@link android.content.pm.ServiceInfo#FOREGROUND_SERVICE_TYPE_SHORT_SERVICE}
      * was added
      * on Android version {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE},
      * it can be also used on