From 8e3ec2a70020a740cc8547e4ffc50fd635a34598 Mon Sep 17 00:00:00 2001
From: Pavel Grafov <pgrafov@google.com>
Date: Wed, 26 Jul 2023 16:36:10 +0100
Subject: [PATCH] Clarify reasons for notification removal.

The removed list of reasons is incomplete and might make developer think
that a notification can't be removed for any other reason. "reason"
argument in one of the overloads provides a link to full list of
reasons.

Annotating the argument with @NotificationCancelReason generates an
equivalent of @param javadoc with the complete list of reasons.

Bug: 292204120
Test: doc-only change
Change-Id: I1394b987e8ccdab474189f5fbb57ea3c70bce50b
---
 .../notification/NotificationListenerService.java    | 12 +-----------
 1 file changed, 1 insertion(+), 11 deletions(-)

diff --git a/core/java/android/service/notification/NotificationListenerService.java b/core/java/android/service/notification/NotificationListenerService.java
index 1d49049ab7d45..07f8aac43bf50 100644
--- a/core/java/android/service/notification/NotificationListenerService.java
+++ b/core/java/android/service/notification/NotificationListenerService.java
@@ -485,9 +485,6 @@ public abstract class NotificationListenerService extends Service {
     /**
      * Implement this method to learn when notifications are removed.
      * <p>
-     * This might occur because the user has dismissed the notification using system UI (or another
-     * notification listener) or because the app has withdrawn the notification.
-     * <p>
      * NOTE: The {@link StatusBarNotification} object you receive will be "light"; that is, the
      * result from {@link StatusBarNotification#getNotification} may be missing some heavyweight
      * fields such as {@link android.app.Notification#contentView} and
@@ -506,9 +503,6 @@ public abstract class NotificationListenerService extends Service {
     /**
      * Implement this method to learn when notifications are removed.
      * <p>
-     * This might occur because the user has dismissed the notification using system UI (or another
-     * notification listener) or because the app has withdrawn the notification.
-     * <p>
      * NOTE: The {@link StatusBarNotification} object you receive will be "light"; that is, the
      * result from {@link StatusBarNotification#getNotification} may be missing some heavyweight
      * fields such as {@link android.app.Notification#contentView} and
@@ -531,9 +525,6 @@ public abstract class NotificationListenerService extends Service {
     /**
      * Implement this method to learn when notifications are removed and why.
      * <p>
-     * This might occur because the user has dismissed the notification using system UI (or another
-     * notification listener) or because the app has withdrawn the notification.
-     * <p>
      * NOTE: The {@link StatusBarNotification} object you receive will be "light"; that is, the
      * result from {@link StatusBarNotification#getNotification} may be missing some heavyweight
      * fields such as {@link android.app.Notification#contentView} and
@@ -546,10 +537,9 @@ public abstract class NotificationListenerService extends Service {
      *            was just removed.
      * @param rankingMap The current ranking map that can be used to retrieve ranking information
      *                   for active notifications.
-     * @param reason see {@link #REASON_LISTENER_CANCEL}, etc.
      */
     public void onNotificationRemoved(StatusBarNotification sbn, RankingMap rankingMap,
-            int reason) {
+            @NotificationCancelReason int reason) {
         onNotificationRemoved(sbn, rankingMap);
     }