From 9844c3a9918f8269a8520572ba2c4abaf038f008 Mon Sep 17 00:00:00 2001
From: Garfield Tan <xutan@google.com>
Date: Fri, 16 Oct 2020 14:03:48 -0700
Subject: [PATCH] Change documentation of window layout affinity

This change rephrases the documentation of window layout affinity to
make it easier to read and adds some examples to elaborates the effect
of this attribute.

Bug: 157149018
Test: TreeHugger is enough.
Change-Id: Ied7f69d2652655f2697a5ea3646f4b6a74b62802
---
 core/res/res/values/attrs_manifest.xml | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index e3ddbd8d25a24..f8266ba177ca5 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -3202,10 +3202,23 @@
         <attr name="minHeight" />
 
         <!-- Window layout affinity of this activity. Activities with the same window layout
-          affinity will share the same layout record. If an activity is launched in freeform window,
-          the activity will be launched to the latest position and size where any task, if the root
-          activity of that task shares the same window layout affinity with the activity being
-          launched. Window layout affinity is shared only among activities with the same UID.
+          affinity will share the same layout record. That is, if a user is opening an activity in
+          a new task on a display that can host freeform windows, and the user had opened a task
+          before and that task had a root activity who had the same window layout affinity, the
+          new task's window will be created in the same window mode and around the location which
+          the previously opened task was in.
+
+          <p>For example, if a user maximizes a task with root activity A and opens another
+          activity B that has the same window layout affinity as activity A has, activity B will
+          be created in fullscreen window mode. Similarly, if they move/resize a task with root
+          activity C and open another activity D that has the same window layout affinity as
+          activity C has, activity D will be in freeform window mode and as close to the position
+          of activity C as conditions permit. It doesn't require the user to keep the task with
+          activity A or activity C open. It won't, however, put any task into split-screen or PIP
+          window mode on launch.
+
+          <p>If the user is opening an activity with its window layout affinity for the first time,
+          the window mode and position is OEM defined.
 
           <p>By default activity doesn't share any affinity with other activities. -->
         <attr name="windowLayoutAffinity" format="string" />