Merge "Add api-level.h to dac, improve docs."
diff --git a/libc/include/android/api-level.h b/libc/include/android/api-level.h
index 50cb61a..bcddddd 100644
--- a/libc/include/android/api-level.h
+++ b/libc/include/android/api-level.h
@@ -29,6 +29,13 @@
#pragma once
/**
+ * @defgroup apilevels API Levels
+ *
+ * Defines functions and constants for working with Android API levels.
+ * @{
+ */
+
+/**
* @file android/api-level.h
* @brief Functions and constants for dealing with multiple API levels.
*
@@ -50,9 +57,40 @@
/* This #ifndef should never be true except when doxygen is generating docs. */
#ifndef __ANDROID_API__
/**
- * `__ANDROID_API__` is the API level being targeted. For the OS,
- * this is `__ANDROID_API_FUTURE__`. For the NDK, this is set by the
- * compiler system based on the API level you claimed to target. See
+ * `__ANDROID_API__` is the [API
+ * level](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
+ * this code is being built for. The resulting binaries are only guaranteed to
+ * be compatible with devices which have an API level greater than or equal to
+ * `__ANDROID_API__`.
+ *
+ * For NDK and APEX builds, this macro will always be defined. It is set
+ * automatically by Clang using the version suffix that is a part of the target
+ * name. For example, `__ANDROID_API__` will be 24 when Clang is given the
+ * argument `-target aarch64-linux-android24`.
+ *
+ * For non-APEX OS code, this defaults to __ANDROID_API_FUTURE__.
+ *
+ * The value of `__ANDROID_API__` can be compared to the named constants in
+ * `<android/api-level.h>`.
+ *
+ * The interpretation of `__ANDROID_API__` is similar to the AndroidManifest.xml
+ * `minSdkVersion`. In most cases `__ANDROID_API__` will be identical to
+ * `minSdkVersion`, but as it is a build time constant it is possible for
+ * library code to use a different value than the app it will be included in.
+ * When libraries and applications build for different API levels, the
+ * `minSdkVersion` of the application must be at least as high as the highest
+ * API level used by any of its libraries which are loaded unconditionally.
+ *
+ * Note that in some cases the resulting binaries may load successfully on
+ * devices with an older API level. That behavior should not be relied upon,
+ * even if you are careful to avoid using new APIs, as the toolchain may make
+ * use of new features by default. For example, additional FORTIFY features may
+ * implicitly make use of new APIs, SysV hashes may be omitted in favor of GNU
+ * hashes to improve library load times, or relocation packing may be enabled to
+ * reduce binary size.
+ *
+ * See android_get_device_api_level(),
+ * android_get_application_target_sdk_version() and
* https://android.googlesource.com/platform/bionic/+/master/docs/defines.md.
*/
#define __ANDROID_API__ __ANDROID_API_FUTURE__
@@ -114,9 +152,9 @@
#define __ANDROID_API_S__ 31
/**
- * Returns the `targetSdkVersion` of the caller, or `__ANDROID_API_FUTURE__`
- * if there is no known target SDK version (for code not running in the
- * context of an app).
+ * Returns the `targetSdkVersion` of the caller, or `__ANDROID_API_FUTURE__` if
+ * there is no known target SDK version (for code not running in the context of
+ * an app).
*
* The returned values correspond to the named constants in `<android/api-level.h>`,
* and is equivalent to the AndroidManifest.xml `targetSdkVersion`.
@@ -148,3 +186,5 @@
#endif
__END_DECLS
+
+/** @} */