Improved Content Capture and LocusId javadocs.
Test: mmm frameworks/base/:doc-comment-check-docs # and checked resulting HTML
Fixes: 123577059
Fixes: 128427733
Fixes: 123954513
Change-Id: I955e99efa099cbb68477b394450fa468c85f352c
diff --git a/core/java/android/content/LocusId.java b/core/java/android/content/LocusId.java
index c67ff7c..283cea0 100644
--- a/core/java/android/content/LocusId.java
+++ b/core/java/android/content/LocusId.java
@@ -18,19 +18,50 @@
import android.annotation.NonNull;
import android.os.Parcel;
import android.os.Parcelable;
+import android.view.contentcapture.ContentCaptureManager;
import com.android.internal.util.Preconditions;
import java.io.PrintWriter;
/**
- * Identifier for an unique state in the application.
+ * An identifier for an unique state (locus) in the application. Should be stable across reboots and
+ * backup / restore.
*
- * <p>Should be stable across reboots and backup / restore.
+ * <p>Locus is a new concept introduced on
+ * {@link android.os.Build.VERSION_CODES#Q Android Q} and it lets the intelligence service provided
+ * by the Android System to correlate state between different subsystems such as content capture,
+ * shortcuts, and notifications.
*
- * <p>For example, a chat app could use the context to resume a conversation between 2 users.
+ * <p>For example, if your app provides an activiy representing a chat between 2 users
+ * (say {@code A} and {@code B}, this chat state could be represented by:
+ *
+ * <pre><code>
+ * LocusId chatId = new LocusId("Chat_A_B");
+ * </code></pre>
+ *
+ * <p>And then you should use that {@code chatId} by:
+ *
+ * <ul>
+ * <li>Setting it in the chat notification (through
+ * {@link android.app.Notification.Builder#setLocusId(LocusId)
+ * Notification.Builder.setLocusId(chatId)}).
+ * <li>Setting it into the {@link android.content.pm.ShortcutInfo} (through
+ * {@link android.content.pm.ShortcutInfo.Builder#setLocusId(LocusId)
+ * ShortcutInfo.Builder.setLocusId(chatId)}), if you provide a launcher shortcut for that chat
+ * conversation.
+ * <li>Associating it with the {@link android.view.contentcapture.ContentCaptureContext} of the
+ * root view of the chat conversation activity (through
+ * {@link android.view.View#getContentCaptureSession()}, then
+ * {@link android.view.contentcapture.ContentCaptureContext.Builder
+ * new ContentCaptureContext.Builder(chatId).build()} and
+ * {@link android.view.contentcapture.ContentCaptureSession#setContentCaptureContext(
+ * android.view.contentcapture.ContentCaptureContext)} - see {@link ContentCaptureManager}
+ * for more info about content capture).
+ * <li>Configuring your app to launch the chat conversation through the
+ * {@link Intent#ACTION_VIEW_LOCUS} intent.
+ * </ul>
*/
-// TODO(b/123577059): make sure this is well documented and understandable
public final class LocusId implements Parcelable {
private final String mId;
@@ -45,7 +76,7 @@
}
/**
- * Gets the {@code id} associated with the locus.
+ * Gets the canonical {@code id} associated with the locus.
*/
@NonNull
public String getId() {
@@ -100,7 +131,7 @@
parcel.writeString(mId);
}
- public static final @android.annotation.NonNull Parcelable.Creator<LocusId> CREATOR =
+ public static final @NonNull Parcelable.Creator<LocusId> CREATOR =
new Parcelable.Creator<LocusId>() {
@NonNull