Merge "Update <system_properties.h> documentation." into main

1 files changed, 39 insertions, 17 deletions

diff --git a/libc/include/sys/system_properties.h b/libc/include/sys/system_properties.h
index dc869da62..ae94db56c 100644
--- a/libc/include/sys/system_properties.h
+++ b/libc/include/sys/system_properties.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _INCLUDE_SYS_SYSTEM_PROPERTIES_H
-#define _INCLUDE_SYS_SYSTEM_PROPERTIES_H
+#pragma once
+
+/**
+ * @file system_properties.h
+ * @brief System properties.
+ */
 
 #include <sys/cdefs.h>
 #include <stdbool.h>
@@ -36,39 +40,53 @@
 
 __BEGIN_DECLS
 
+/** An opaque structure representing a system property. */
 typedef struct prop_info prop_info;
 
+/**
+ * The limit on the length of a property value.
+ * (See PROP_NAME_MAX for property names.)
+ */
 #define PROP_VALUE_MAX  92
 
-/*
+/**
  * Sets system property `name` to `value`, creating the system property if it doesn't already exist.
+ *
+ * Returns 0 on success, or -1 on failure.
  */
 int __system_property_set(const char* _Nonnull __name, const char* _Nonnull __value);
 
-/*
+/**
  * Returns a `prop_info` corresponding system property `name`, or nullptr if it doesn't exist.
- * Use __system_property_read_callback to query the current value.
+ * Use __system_property_read_callback() to query the current value.
  *
- * Property lookup is expensive, so it can be useful to cache the result of this function.
+ * Property lookup is expensive, so it can be useful to cache the result of this
+ * function rather than using __system_property_get().
  */
 const prop_info* _Nullable __system_property_find(const char* _Nonnull __name);
 
-/*
- * Calls `callback` with a consistent trio of name, value, and serial number for property `pi`.
+/**
+ * Calls `callback` with a consistent trio of name, value, and serial number
+ * for property `pi`.
+ *
+ * Available since API level 26.
  */
 void __system_property_read_callback(const prop_info* _Nonnull __pi,
     void (* _Nonnull __callback)(void* _Nullable __cookie, const char* _Nonnull __name, const char* _Nonnull __value, uint32_t __serial),
     void* _Nullable __cookie) __INTRODUCED_IN(26);
 
-/*
+/**
  * Passes a `prop_info` for each system property to the provided
- * callback.  Use __system_property_read_callback() to read the value.
+ * callback. Use __system_property_read_callback() to read the value of
+ * any of the properties.
  *
  * This method is for inspecting and debugging the property system, and not generally useful.
+ *
+ * Returns 0 on success, or -1 on failure.
  */
 int __system_property_foreach(void (* _Nonnull __callback)(const prop_info* _Nonnull __pi, void* _Nullable __cookie), void* _Nullable __cookie);
 
-/*
+/**
  * Waits for the specific system property identified by `pi` to be updated
  * past `old_serial`. Waits no longer than `relative_timeout`, or forever
  * if `relative_timeout` is null.
@@ -79,20 +97,24 @@ int __system_property_foreach(void (* _Nonnull __callback)(const prop_info* _Non
  *
  * Returns true and updates `*new_serial_ptr` on success, or false if the call
  * timed out.
+ *
+ * Available since API level 26.
  */
 struct timespec;
 bool __system_property_wait(const prop_info* _Nullable __pi, uint32_t __old_serial, uint32_t* _Nonnull __new_serial_ptr, const struct timespec* _Nullable __relative_timeout)
     __INTRODUCED_IN(26);
 
-/* Deprecated. In Android O and above, there's no limit on property name length. */
+/**
+ * Deprecated: there's no limit on the length of a property name since
+ * API level 26, though the limit on property values (PROP_VALUE_MAX) remains.
+ */
 #define PROP_NAME_MAX   32
-/* Deprecated. Use __system_property_read_callback instead. */
+
+/** Deprecated. Use __system_property_read_callback() instead. */
 int __system_property_read(const prop_info* _Nonnull __pi, char* _Nullable __name, char* _Nonnull __value);
-/* Deprecated. Use __system_property_read_callback instead. */
+/** Deprecated. Use __system_property_read_callback() instead. */
 int __system_property_get(const char* _Nonnull __name, char* _Nonnull __value);
-/* Deprecated. Use __system_property_foreach instead. */
+/** Deprecated. Use __system_property_foreach() instead. */
 const prop_info* _Nullable __system_property_find_nth(unsigned __n);
 
 __END_DECLS
-
-#endif