Add documentation about the purpose of #apex and #symbols in map.txt
Currently we document the semantics of these two symbols. I would like
to add some documentation about why this granularity is necessary. The
majority of the details are contained in b/191371676
Test: N/A (documentation change)
Bug: 265485106
Change-Id: I752c921eabceff94f92f24a46c9a16dc28a2af19
diff --git a/cc/library.go b/cc/library.go
index 5760071..fe1d00d 100644
--- a/cc/library.go
+++ b/cc/library.go
@@ -1250,6 +1250,10 @@
// b/239274367 --apex and --systemapi filters symbols tagged with # apex and #
// systemapi, respectively. The former is for symbols defined in platform libraries
// and the latter is for symbols defined in APEXes.
+ // A single library can contain either # apex or # systemapi, but not both.
+ // The stub generator (ndkstubgen) is additive, so passing _both_ of these to it should be a no-op.
+ // However, having this distinction helps guard accidental
+ // promotion or demotion of API and also helps the API review process b/191371676
var flag string
if ctx.Module().(android.ApexModule).NotInPlatform() {
flag = "--apex"