Start documenting libc.
Bug: N/A
Test: N/A
Change-Id: I17345cb72a5ffc3af1688cf5874589cfb1e1fea0
diff --git a/libc/include/uchar.h b/libc/include/uchar.h
index e59d6a9..90af651 100644
--- a/libc/include/uchar.h
+++ b/libc/include/uchar.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _UCHAR_H_
-#define _UCHAR_H_
+#pragma once
+
+/**
+ * @file uchar.h
+ * @brief Unicode functions.
+ */
#include <stddef.h>
#include <sys/cdefs.h>
@@ -36,18 +40,54 @@
__BEGIN_DECLS
#if !defined(__cplusplus)
+/** The UTF-16 character type. */
typedef __CHAR16_TYPE__ char16_t;
+/** The UTF-32 character type. */
typedef __CHAR32_TYPE__ char32_t;
#endif
+/** On Android, char16_t is UTF-16. */
#define __STD_UTF_16__ 1
+
+/** On Android, char32_t is UTF-32. */
#define __STD_UTF_32__ 1
-size_t c16rtomb(char* __buf, char16_t __ch16, mbstate_t* __ps) __INTRODUCED_IN(21);
-size_t c32rtomb(char* __buf, char32_t __ch32, mbstate_t* __ps) __INTRODUCED_IN(21);
-size_t mbrtoc16(char16_t* __ch16, const char* __s, size_t __n, mbstate_t* __ps) __INTRODUCED_IN(21);
-size_t mbrtoc32(char32_t* __ch32, const char* __s, size_t __n, mbstate_t* __ps) __INTRODUCED_IN(21);
+/**
+ * [c16rtomb(3)](http://man7.org/linux/man-pages/man3/c16rtomb.3.html) converts a single UTF-16
+ * character to UTF-8.
+ *
+ * Returns the number of bytes written to `__buf` on success, and returns -1 and sets `errno`
+ * on failure.
+ *
+ * Available since API level 21.
+ */
+size_t c16rtomb(char* _Nullable __buf, char16_t __ch16, mbstate_t* _Nullable __ps) __INTRODUCED_IN(21);
+
+/**
+ * [c32rtomb(3)](http://man7.org/linux/man-pages/man3/c32rtomb.3.html) converts a single UTF-32
+ * character to UTF-8.
+ *
+ * Returns the number of bytes written to `__buf` on success, and returns -1 and sets `errno`
+ * on failure.
+ *
+ * Available since API level 21.
+ */
+size_t c32rtomb(char* _Nullable __buf, char32_t __ch32, mbstate_t* _Nullable __ps) __INTRODUCED_IN(21);
+
+/**
+ * [mbrtoc16(3)](http://man7.org/linux/man-pages/man3/mbrtoc16.3.html) converts the next UTF-8
+ * sequence to a UTF-16 code point.
+ *
+ * Available since API level 21.
+ */
+size_t mbrtoc16(char16_t* _Nullable __ch16, const char* _Nullable __s, size_t __n, mbstate_t* _Nullable __ps) __INTRODUCED_IN(21);
+
+/**
+ * [mbrtoc32(3)](http://man7.org/linux/man-pages/man3/mbrtoc32.3.html) converts the next UTF-8
+ * sequence to a UTF-32 code point.
+ *
+ * Available since API level 21.
+ */
+size_t mbrtoc32(char32_t* _Nullable __ch32, const char* _Nullable __s, size_t __n, mbstate_t* _Nullable __ps) __INTRODUCED_IN(21);
__END_DECLS
-
-#endif