Minor updates and freshness for misc API guidelines

PiperOrigin-RevId: 557139290
Change-Id: Ia51892bfc0ad4ea2be4f670b84ba6e74c20ffd3d

1 files changed, 17 insertions, 11 deletions

diff --git a/api-guidelines/index.md b/api-guidelines/index.md
index 61bf254..a30cc40 100644
--- a/api-guidelines/index.md
+++ b/api-guidelines/index.md
@@ -15,7 +15,7 @@ tool.
 
 ## API Lint tool {#apilint}
 
-[API Lint](https://cs.android.com/android/platform/superproject/+/master:tools/metalava/src/main/java/com/android/tools/metalava/ApiLint.kt)
+[API Lint](https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:tools/metalava/src/main/java/com/android/tools/metalava/ApiLint.kt)
 is integrated into the Metalava static analysis tool and runs as part of the
 platform build. You can run it manually from an
 [AOSP checkout](https://source.android.com/setup/build/downloading) with:
@@ -36,7 +36,7 @@ than in the ideal rules laid out herein.
 The rules are a work in progress and will be added to in the future as other
 patterns emerge from future API reviews.
 
-## API Basics <a name="basics"></a>
+## API basics <a name="basics"></a>
 
 This category pertains to the core aspects of an Android API.
 
@@ -51,20 +51,20 @@ Unimplemented API surfaces have multiple issues:
 -   There is no guarantee that a proper or complete surface has been exposed.
     Until an API is tested or used by clients, there is no way to verify a
     client has the appropriate APIs to be able to use the feature.
--   APIs without implementation cannot be tested in Developer Previews.
--   APIs without implementation cannot be tested in CTS.
--   By definition, APIs without implementation are not IC complete.
+-   APIs without implementation cannot be tested in Developer Previews
+-   APIs without implementation cannot be tested in CTS
+-   By definition, APIs without implementation are not IC complete
 
 ### All APIs must be tested <a name="basics-tested"></a>
 
 This is in line with CTS requirements and implementation expectation.
 
 Testing API surfaces provides a base guarantee that the API surface is usable
-and we've exposed all the necessary aspects.  Testing for existence is not
+and we've exposed all the necessary aspects. Testing for existence is not
 sufficient; the API functionality itself must be tested.
 
-You should be able to answer the question of "How will a developer test your
-API?"
+APIs should also be _testable_. You should be able to answer the question, "How
+will an app developer test code that uses your API?"
 
 ### All APIs must be documented <a name="basics-documented"></a>
 
@@ -79,7 +79,8 @@ especially in the public API.
 
 ### Follow standard Java coding conventions, except where noted <a name="style-conventions"></a>
 
-There are Android coding conventions posted for external contributors here:
+Android's platform coding conventions are documented for external contributors
+here:
 
 https://source.android.com/source/code-style.html
 
@@ -147,7 +148,8 @@ specific guidance.
 
 Kotlin uses `companion object` to expose static members. In some cases, these
 will show up from Java on an inner class named `Companion` rather than on the
-containing class.
+containing class. `Companion` classes may show as empty classes in API text
+files -- that is working as intended.
 
 To maximize compatibility with Java, annotate companion objects'
 [non-`const` fields](https://developer.android.com/kotlin/interop#companion_constants)
@@ -166,7 +168,7 @@ companion object {
 
 <!--#include file="/api-guidelines/evolution.md"-->
 
-## XML Schemas <a name="xml"></a>
+## XML schemas <a name="xml"></a>
 
 If an XML schema serves as a stable interface between components, that schema
 must be explicitly specified and must evolve in a backward-compatible manner,
@@ -174,6 +176,10 @@ similar to other Android APIs. For example, the structure of XML elements and
 attributes must be preserved similar to how methods and variables are maintained
 on other Android API surfaces.
 
+NOTE API Council does not explicitly review XML schemas and AOSP does not have
+tooling to automatically ensure compatibility for XML schemas or parsing.
+Proceed with caution.
+
 ### Deprecation best-practices <a name="xml-deprecation"></a>
 
 If you'd like to deprecate an XML element or attribute, you can add the