Doc updates for #apex and #systemapi

These include
- Drop the synonym sentence. With the enforcement introduced in
  aosp/2153678, they can no longer be used interchangeably
- Add information that a single .map.txt file cannot contain both these
  two annotations.
- Link a bug that provides additional context on why this granularity
  is necessary.

Test: N/A
Bug: 266824291
Change-Id: I31b49d492ec56f2f6f0b88de6e608e4ec6fe7011

1 files changed, 18 insertions, 3 deletions

diff --git a/docs/map_files.md b/docs/map_files.md
index 13880591a..35e8cbbfc 100644
--- a/docs/map_files.md
+++ b/docs/map_files.md
@@ -148,9 +148,24 @@ from access via `dlsym`, but this is not always possible.
 
 ### systemapi
 
-This is a synonym of the `apex` tag. It should be used to clarify that the API
-is an API exposed by the system for an APEX, whereas `apex` should be used for
-APIs exposed by an APEX to the platform or another APEX.
+Indicates that the symbol is exposed by the platform for an apex. Whereas `apex`
+should be used for APIs exposed by an APEX to the platform or another APEX.
+
+May be used in combination with `llndk` if the symbol is exposed to both APEX
+and the LL-NDK.
+
+Since a single library can be installed ether in platform or an apex, but not
+both, a single map.txt file should not contain _both_ # apex and # systemapi symbols.
+
+The granularity between # apex and # systemapi exists to help the API review
+process (b/191371676). These two symbols have very similar lifetime "in
+practice". A #systemapi symbol can be dropped from the next release if we are
+confident that no one is using it. Similarily, #apex can be dropped if we are
+sure that the old platform which used the symbol has reached EOL and thus is no
+longer accepting new APEX updates. Unlike the APIs for apps where we have zero
+control over how APIs are used, we are in a much more controllable environment
+when talking about #systemapi and #apex symbols. So, we have some flexibility
+here when determining the lifetime of a symbol.
 
 ### var