Make it clearer that the macro names for API levels are deprecated.
Numeric API levels have always been the lingua franca, with confusion between "dessert" names and "marketing" names (which are sometimes, as currently, themselves numbers). With the alphabet wrapping making "dessert" names less useful, we can finally put a stop to this. (The symbol version names already switched to being numeric.)
Change-Id: Ic0da9c0b709200c3065d735369c231f04be7bbc9
diff --git a/libc/include/android/api-level.h b/libc/include/android/api-level.h
index c9536c1..9550b91 100644
--- a/libc/include/android/api-level.h
+++ b/libc/include/android/api-level.h
@@ -31,13 +31,13 @@
/**
* @defgroup apilevels API Levels
*
- * Defines functions and constants for working with Android API levels.
+ * Defines functions for working with Android API levels.
* @{
*/
/**
* @file android/api-level.h
- * @brief Functions and constants for dealing with multiple API levels.
+ * @brief Functions for dealing with multiple API levels.
*
* See
* https://android.googlesource.com/platform/bionic/+/main/docs/defines.md.
@@ -96,82 +96,64 @@
#define __ANDROID_API__ __ANDROID_API_FUTURE__
#endif
-/** Names the Gingerbread API level (9), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 9. Prefer numeric API levels in new code. */
#define __ANDROID_API_G__ 9
-/** Names the Ice-Cream Sandwich API level (14), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 14. Prefer numeric API levels in new code. */
#define __ANDROID_API_I__ 14
-/** Names the Jellybean API level (16), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 16. Prefer numeric API levels in new code. */
#define __ANDROID_API_J__ 16
-/** Names the Jellybean MR1 API level (17), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 17. Prefer numeric API levels in new code. */
#define __ANDROID_API_J_MR1__ 17
-/** Names the Jellybean MR2 API level (18), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 18. Prefer numeric API levels in new code. */
#define __ANDROID_API_J_MR2__ 18
-/** Names the KitKat API level (19), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 19. Prefer numeric API levels in new code. */
#define __ANDROID_API_K__ 19
-/** Names the Lollipop API level (21), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 21. Prefer numeric API levels in new code. */
#define __ANDROID_API_L__ 21
-/** Names the Lollipop MR1 API level (22), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 22. Prefer numeric API levels in new code. */
#define __ANDROID_API_L_MR1__ 22
-/** Names the Marshmallow API level (23), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 23. Prefer numeric API levels in new code. */
#define __ANDROID_API_M__ 23
-/** Names the Nougat API level (24), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 24. Prefer numeric API levels in new code. */
#define __ANDROID_API_N__ 24
-/** Names the Nougat MR1 API level (25), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 25. Prefer numeric API levels in new code. */
#define __ANDROID_API_N_MR1__ 25
-/** Names the Oreo API level (26), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 26. Prefer numeric API levels in new code. */
#define __ANDROID_API_O__ 26
-/** Names the Oreo MR1 API level (27), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 27. Prefer numeric API levels in new code. */
#define __ANDROID_API_O_MR1__ 27
-/** Names the Pie API level (28), for comparison against `__ANDROID_API__`. */
+/** Deprecated name for API level 28. Prefer numeric API levels in new code. */
#define __ANDROID_API_P__ 28
-/**
- * Names the Android 10 (aka "Q" or "Quince Tart") API level (29), for
- * comparison against `__ANDROID_API__`.
- */
+/** Deprecated name for API level 29. Prefer numeric API levels in new code. */
#define __ANDROID_API_Q__ 29
-/**
- * Names the Android 11 (aka "R" or "Red Velvet Cake") API level (30), for
- * comparison against `__ANDROID_API__`.
- */
+/** Deprecated name for API level 30. Prefer numeric API levels in new code. */
#define __ANDROID_API_R__ 30
-/**
- * Names the Android 12 (aka "S" or "Snowcone") API level (31), for
- * comparison against `__ANDROID_API__`.
- */
+/** Deprecated name for API level 31. Prefer numeric API levels in new code. */
#define __ANDROID_API_S__ 31
-/**
- * Names the Android 13 (aka "T" or "Tiramisu") API level (33), for
- * comparison against `__ANDROID_API__`.
- */
+/** Deprecated name for API level 33. Prefer numeric API levels in new code. */
#define __ANDROID_API_T__ 33
-/**
- * Names the Android 14 (aka "U" or "UpsideDownCake") API level (34),
- * for comparison against `__ANDROID_API__`.
- */
+/** Deprecated name for API level 34. Prefer numeric API levels in new code. */
#define __ANDROID_API_U__ 34
-/**
- * Names the Android 15 (aka "V" or "VanillaIceCream") API level (35),
- * for comparison against `__ANDROID_API__`.
- */
+/** Deprecated name for API level 35. Prefer numeric API levels in new code. */
#define __ANDROID_API_V__ 35
/* This file is included in <features.h>, and might be used from .S files. */