Project import generated by Copybara.
Test: N/A
PiperOrigin-RevId: 367034341
Change-Id: I8c9fd130b8f32367f1f4b287fb09dde8aba93fe9
diff --git a/docs/api_guidelines.md b/docs/api_guidelines.md
index 88a2b26..f04be61 100644
--- a/docs/api_guidelines.md
+++ b/docs/api_guidelines.md
@@ -80,6 +80,12 @@
to discover this solution from the class duplication error raised at compile
time.
+Same-version groups are a special case for this rule. Existing modules that are
+already in a same-version group may be split into sub-modules provided that (a)
+the sub-modules are also in the same-version group and (b) the full API surface
+of the existing module is preserved through transitive dependencies, e.g. the
+sub-modules are added as dependencies of the existing module.
+
#### Same-version (atomic) groups {#modules-atomic}
Library groups are encouraged to opt-in to a same-version policy whereby all
@@ -732,6 +738,10 @@
Deprecation is an non-breaking API change that must occur in a **major** or
**minor** release.
+APIs that are added during a pre-release cycle and marked as `@Deprecated`
+within the same cycle, e.g. added in `alpha01` and deprecated in `alpha06`,
+[must be removed](versioning.md#beta-checklist) before moving to `beta01`.
+
### Soft removal (@removed)
Soft removal preserves binary compatibility while preventing source code from
@@ -1166,10 +1176,10 @@
### Restricted APIs {#restricted-api}
Jetpack's library tooling supports hiding Java-visible (ex. `public` and
-`protected`) APIs from developers using a combination of the `@hide` docs
-annotation and `@RestrictTo` source annotation. These annotations **must** be
-paired together when used, and are validated as part of presubmit checks for
-Java code (Kotlin not yet supported by Checkstyle).
+`protected`) APIs from developers using a combination of the `@RestrictTo`
+source annotation, and the `@hide` docs annotation (`@suppress` in Kotlin).
+These annotations **must** be paired together when used, and are validated as
+part of presubmit checks for Java code (Kotlin not yet supported by Checkstyle).
The effects of hiding an API are as follows:
@@ -1184,22 +1194,22 @@
#### When to use `@hide` {#restricted-api-usage}
-Generally, avoid using `@hide`. The `@hide` annotation indicates that developers
-should not call an API that is _technically_ public from a Java visibility
-perspective. Hiding APIs is often a sign of a poorly-abstracted API surface, and
-priority should be given to creating public, maintainable APIs and using Java
-visibility modifiers.
+In other cases, avoid using `@hide` / `@suppress`. These annotations indicates
+that developers should not call an API that is _technically_ public from a Java
+visibility perspective. Hiding APIs is often a sign of a poorly-abstracted API
+surface, and priority should be given to creating public, maintainable APIs and
+using Java visibility modifiers.
-*Do not* use `@hide` to bypass API tracking and review for production APIs;
-instead, rely on API+1 and API Council review to ensure APIs are reviewed on a
-timely basis.
+*Do not* use `@hide`/`@suppress` to bypass API tracking and review for
+production APIs; instead, rely on API+1 and API Council review to ensure APIs
+are reviewed on a timely basis.
-*Do not* use `@hide` for implementation detail APIs that are used between
-libraries and could reasonably be made public.
+*Do not* use `@hide`/`@suppress` for implementation detail APIs that are used
+between libraries and could reasonably be made public.
-*Do* use `@hide` paired with `@RestrictTo(LIBRARY)` for implementation detail
-APIs used within a single library (but prefer Java language `private` or
-`default` visibility).
+*Do* use `@hide`/`@suppress` paired with `@RestrictTo(LIBRARY)` for
+implementation detail APIs used within a single library (but prefer Java
+language `private` or `default` visibility).
#### `RestrictTo.Scope` and inter- versus intra-library API surfaces {#private-api-types}
@@ -1386,6 +1396,75 @@
### Kotlin {#kotlin}
+#### Nullability from Java (new APIs)
+
+All new Java APIs should be annotated either `@Nullable` or `@NonNull` for all
+reference parameters and reference return types.
+
+```java
+ @Nullable
+ public Object someNewApi(@NonNull Thing arg1, @Nullable List<WhatsIt> arg2) {
+ if(/** something **/) {
+ return someObject;
+ } else {
+ return null;
+ }
+```
+
+#### Nullability from Java (existing APIs)
+
+Adding `@Nullable` or `@NonNull` annotations to existing APIs to document their
+existing nullability is OK. This is a source breaking change for Kotlin
+consumers, and you should ensure that it's noted in the release notes and try to
+minimize the frequency of these updates in releases.
+
+Changing the nullability of an API is a breaking change.
+
+#### Extending APIs that expose types without nullability annotations
+
+[Platform types](https://kotlinlang.org/docs/java-interop.html#null-safety-and-platform-types)
+are exposed by Java types that do not have a `@Nullable` or `@NonNull`
+annotation. In Kotlin they are indicated with the `!` suffix.
+
+When interacting with an Android platform API that exposes APIs with unknown
+nullability follow these rules:
+
+1. If wrapping the type in a new API, define and handle `@Nullable` or
+ `@NonNull` in the library. Treat types with unknown nullability passed into
+ or return from Android as `@Nullable` in the library.
+2. If extending an existing API (e.g. `@Override`), pass through the existing
+ types with unknown nullability and annotate each with
+ `@SuppressLint("UnknownNullness")`
+
+In Kotlin, a type with unknown nullability is exposed as a "platform type"
+(indicated with a `!` suffix) which has unknown nullability in the type checker,
+and may bypass type checking leading to runtime errors. When possible, do not
+directly expose types with unknown nullability in new public APIs.
+
+#### Extending `@RecentlyNonNull` and `@RecentlyNullable` APIs
+
+Platform APIs are annotated in the platform SDK artifacts with fake annotations
+`@RecentlyNonNull` and `@RecentlyNullable` to avoid breaking builds when we
+annotated platform APIs with nullability. These annotations cause warnings
+instead of build failures. The `RecentlyNonNull` and `RecentlyNullable`
+annotations are added by Metalava and do not appear in platform code.
+
+When extending an API that is annotated `@RecentlyNonNull`, you should annotate
+the override with `@NonNull`, and the same for `@RecentlyNullable` and
+`@Nullable`.
+
+For example `SpannableStringBuilder.append` is annotated `RecentlyNonNull` and
+an override should look like:
+
+```java
+ @NonNull
+ @Override
+ public SpannableStringBuilder append(@SuppressLint("UnknownNullness") CharSequence text) {
+ super.append(text);
+ return this;
+ }
+```
+
#### Data classes {#kotlin-data}
Kotlin `data` classes provide a convenient way to define simple container
diff --git a/docs/kdoc_guidelines.md b/docs/kdoc_guidelines.md
index c53ba8c..ef33b04 100644
--- a/docs/kdoc_guidelines.md
+++ b/docs/kdoc_guidelines.md
@@ -117,6 +117,68 @@
class Item
```
+### Include class name in `@see`
+
+When referring to a function using `@see`, include the class name with the
+function - even if the function the `see` is referring to is in the same class.
+
+Instead of:
+
+```kotlin {.bad}
+/**
+ * @see .myCoolFun
+ */
+```
+
+Do this:
+
+```kotlin {.good}
+/**
+ * @see MyCoolClass.myCoolFun
+ */
+```
+
+### Match `@param` with usage
+
+When using `@param` to refer to a variable, the spelling must match the
+variable's code declaration.
+
+Instead of:
+
+```kotlin {.bad}
+/**
+ * @param myParam
+ */
+public var myParameter: String
+```
+
+Do this:
+
+```kotlin {.good}
+/**
+ * @param myParameter
+ */
+public var myParameter: String
+```
+
+### Don't mix `@see` and Markdown links
+
+Instead of:
+
+```kotlin {.bad}
+/**
+ * @see [MyCoolClass.myCoolFun()][androidx.library.myCoolFun] for more details.
+ */
+```
+
+Do this:
+
+```kotlin {.good}
+/**
+ * See [MyCoolClass.myCoolFun()][androidx.library.myCoolFun] for more details.
+ */
+```
+
## Javadoc - KDoc differences
Some tags are shared between Javadoc and KDoc, such as `@param`, but there are
diff --git a/docs/lint_guide.md b/docs/lint_guide.md
index 649eca3..c1b56c4 100644
--- a/docs/lint_guide.md
+++ b/docs/lint_guide.md
@@ -5,10 +5,15 @@
## Getting started
Lint is a static analysis tool that checks Android project source files. Lint
-checks come with Android Studio by default, but custom Lint checks can be added
+checks come with Android Studio by default, but custom lint checks can be added
to specific library modules to help avoid potential bugs and encourage best code
practices.
+This guide is targeted to developers who would like to quickly get started with
+adding lint checks in the AndroidX development workflow. For a complete guide to
+writing and running lint checks, see the official
+[Android lint documentation](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/docs/README.md.html).
+
### Create a module
If this is the first Lint rule for a library, you will need to create a module
diff --git a/docs/onboarding.md b/docs/onboarding.md
index ed9452b..5715972 100644
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -265,7 +265,7 @@
Note that debugging will not be available until Gradle sync has completed.
-## From the command line
+#### From the command line
Tasks may also be debugged from the command line, which may be useful if
`./studiow` cannot run due to a Gradle task configuration issue.
@@ -289,7 +289,7 @@
./gradlew --stop
```
-Note: This is described in more detail in this
+NOTE This is described in more detail in this
[Medium article](https://medium.com/grandcentrix/how-to-debug-gradle-plugins-with-intellij-eef2ef681a7b).
#### Attaching to an annotation processor
@@ -365,10 +365,10 @@
`{androidx-main-checkout}/frameworks/support/buildSrc/src/main/kotlin/androidx/build/PublishDocsRules.kt`
and uses the prebuilt checked into
`{androidx-main-checkout}/prebuilts/androidx/internal/androidx/`. We
-colloquially refer to this two step process of (1) updating PublishDocsRules.kt
-and (2) checking in a prebuilt artifact into the prebuilts directory as
-[The Prebuilts Dance](releasing.md#the-prebuilts-dance™). So, to build javadocs
-that will be published to
+colloquially refer to this two step process of (1) updating
+`PublishDocsRules.kt` and (2) checking in a prebuilt artifact into the prebuilts
+directory as [The Prebuilts Dance](releasing_detailed.md#the-prebuilts-dance™).
+So, to build javadocs that will be published to
https://developer.android.com/reference/androidx/packages, both of these steps
need to be completed.
@@ -507,7 +507,7 @@
`androidx-platform-dev` branch, you may need to update these prebuilts to obtain
the latest API changes.
-### Missing external dependency
+#### Missing external dependency
If Gradle cannot resolve a dependency listed in your `build.gradle`, you may
need to import the corresponding artifact into `prebuilts/androidx/external`.
@@ -597,10 +597,10 @@
## Library snapshots {#snapshots}
-### Quick how to
+### Quick how-to
Add the following snippet to your build.gradle file, replacing `buildId` with a
-snapshot build Id.
+snapshot build ID.
```groovy {highlight=context:[buildId]}
allprojects {
@@ -612,8 +612,8 @@
}
```
-You must define dependencies on artifacts using the SNAPSHOT version suffix, for
-example:
+You must define dependencies on artifacts using the `SNAPSHOT` version suffix,
+for example:
```groovy {highlight=context:SNAPSHOT}
dependencies {
diff --git a/docs/versioning.md b/docs/versioning.md
index 00ad1d4..27efde7 100644
--- a/docs/versioning.md
+++ b/docs/versioning.md
@@ -241,7 +241,7 @@
exceptions **must** be accompanied by a justification explaining why the change
cannot be made in a future minor version.
-#### Checklist for moving to `beta01`
+#### Checklist for moving to `beta01` {#beta-checklist}
* API surface
* Entire API surface has been reviewed by API Council
