Freshness for top-viewed API Council docs
Also make dH stop warning about missing a Drive link.
PiperOrigin-RevId: 625366116
Change-Id: I1163bac26483375055a569521a042126d7b5148a
diff --git a/api-guidelines/index.md b/api-guidelines/index.md
index fa341cf..d24a9b8 100644
--- a/api-guidelines/index.md
+++ b/api-guidelines/index.md
@@ -1,15 +1,14 @@
# Android API Guidelines
-This document is intended to be a general guide for developers to use to adhere
-to the general principles that the API Council enforces in API reviews.
+This document is intended to be a guide for developers to understand the general
+principles that the API Council enforces in API reviews.
-In addition to understanding and following these guidelines when writing APIs,
-developers should run the API Lint tool, which encodes many of these rules in
-checks that it runs against APIs.
+In addition to following these guidelines when writing APIs, developers should
+run the [API Lint](#apilint) tool, which encodes many of these rules in checks
+that it runs against APIs.
Think of this as the guide to the rules that are obeyed by that Lint tool, plus
-guidelines and general advice on rules that cannot be easily codified into that
-tool.
+general advice on rules that cannot be easily codified into that tool.
[TOC]
@@ -18,12 +17,9 @@
[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:
-
-```bash
-# Run lint on all APIs
-$ m checkapi
-```
+[AOSP platform checkout](https://source.android.com/setup/build/downloading)
+using `m checkapi`. To run the tool from a Jetpack checkout, run the `./gradlew
+checkApi` task.
## API rules {#rules}
@@ -42,7 +38,7 @@
### All APIs must be implemented <a name="basics-implemented"></a>
-Irrespective of an API's audience (Public, @SystemApi, etc), all API surfaces
+Irrespective of an API's audience (public, `@SystemApi`, etc.), all API surfaces
must be implemented when merged or exposed as API. Merging API stubs with
implementation to come at a later date would be a violation of this guideline.
@@ -84,9 +80,10 @@
[flaggedapi]: https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:frameworks/libs/modules-utils/java/android/annotation/FlaggedApi.java?q=symbol%3A%5Cbandroid.annotation.FlaggedApi%5Cb%20case%3Ayes
Note: For FAQ on API flagging, please visit
-[FAQ on API Flagging](/api-guidelines/faq.md) page
+[FAQ on API Flagging](/api-guidelines/faq.md)
+page.
-### All auto-generated APIs must be compliant with the guidelines <a name="basics-auto-generated-code"></a>
+### All generated APIs must be compliant with the guidelines <a name="basics-auto-generated-code"></a>
APIs generated by tools must follow the API guidelines just the same as
hand-written code.
