diff --git a/libs/arect/include/android/rect.h b/libs/arect/include/android/rect.h
index 80741c0..b36728e 100644
--- a/libs/arect/include/android/rect.h
+++ b/libs/arect/include/android/rect.h
@@ -33,23 +33,26 @@
 #endif
 
 /**
- * {@link ARect} is a struct that represents a rectangular window area.
+ * Rectangular window area.
  *
- * It is used with {@link
- * ANativeActivityCallbacks::onContentRectChanged} event callback and
- * ANativeWindow_lock() function.
+ * This is the NDK equivalent of the android.graphics.Rect class in Java. It is
+ * used with {@link ANativeActivityCallbacks::onContentRectChanged} event
+ * callback and the ANativeWindow_lock() function.
+ *
+ * In a valid ARect, left <= right and top <= bottom. ARect with left=0, top=10,
+ * right=1, bottom=11 contains only one pixel at x=0, y=10.
  */
 typedef struct ARect {
 #ifdef __cplusplus
     typedef int32_t value_type;
 #endif
-    /** left position */
+    /// Minimum X coordinate of the rectangle.
     int32_t left;
-    /** top position */
+    /// Minimum Y coordinate of the rectangle.
     int32_t top;
-    /** left position */
+    /// Maximum X coordinate of the rectangle.
     int32_t right;
-    /** bottom position */
+    /// Maximum Y coordinate of the rectangle.
     int32_t bottom;
 } ARect;
 
diff --git a/libs/nativewindow/include/android/hardware_buffer.h b/libs/nativewindow/include/android/hardware_buffer.h
index a477bf2..cc67aca 100644
--- a/libs/nativewindow/include/android/hardware_buffer.h
+++ b/libs/nativewindow/include/android/hardware_buffer.h
@@ -41,9 +41,11 @@
     AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM           = 1,
 
     /**
+     * 32 bits per pixel, 8 bits per channel format where alpha values are
+     * ignored (always opaque).
      * Corresponding formats:
      *   Vulkan: VK_FORMAT_R8G8B8A8_UNORM
-     *   OpenGL ES: GL_RGBA8
+     *   OpenGL ES: GL_RGB8
      */
     AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM           = 2,
 
@@ -124,40 +126,49 @@
     AHARDWAREBUFFER_FORMAT_S8_UINT                  = 0x35,
 };
 
+/**
+ * Buffer usage flags, specifying how the buffer will be accessed.
+ */
 enum {
-    /* The buffer will never be read by the CPU */
+    /// The buffer will never be read by the CPU.
     AHARDWAREBUFFER_USAGE_CPU_READ_NEVER        = 0UL,
-    /* The buffer will sometimes be read by the CPU */
+    /// The buffer will sometimes be read by the CPU.
     AHARDWAREBUFFER_USAGE_CPU_READ_RARELY       = 2UL,
-    /* The buffer will often be read by the CPU */
+    /// The buffer will often be read by the CPU.
     AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN        = 3UL,
-    /* CPU read value mask */
+    /// CPU read value mask.
     AHARDWAREBUFFER_USAGE_CPU_READ_MASK         = 0xFUL,
 
-    /* The buffer will never be written by the CPU */
+    /// The buffer will never be written by the CPU.
     AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER       = 0UL << 4,
-    /* The buffer will sometimes be written to by the CPU */
+    /// The buffer will sometimes be written to by the CPU.
     AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY      = 2UL << 4,
-    /* The buffer will often be written to by the CPU */
+    /// The buffer will often be written to by the CPU.
     AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN       = 3UL << 4,
-    /* CPU write value mask */
+    /// CPU write value mask.
     AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK        = 0xFUL << 4,
 
-    /* The buffer will be read from by the GPU */
+    /// The buffer will be read from by the GPU as a texture.
     AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE      = 1UL << 8,
-    /* The buffer will be written to by the GPU */
+    /**
+     * The buffer will be written to by the GPU as a framebuffer attachment.
+     * Note that the name of this flag is somewhat misleading: it does not imply
+     * that the buffer contains a color format. A buffer with depth or stencil
+     * format that will be used as a framebuffer attachment should also have
+     * this flag.
+     */
     AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT       = 1UL << 9,
-    /* The buffer must not be used outside of a protected hardware path */
+    /// The buffer must not be used outside of a protected hardware path.
     AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT      = 1UL << 14,
-    /* The buffer will be read by a hardware video encoder */
+    /// The buffer will be read by a hardware video encoder.
     AHARDWAREBUFFER_USAGE_VIDEO_ENCODE           = 1UL << 16,
-    /* The buffer will be used for sensor direct data */
+    /// The buffer will be used for direct writes from sensors.
     AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA     = 1UL << 23,
-    /* The buffer will be used as a shader storage or uniform buffer object */
+    /// The buffer will be used as a shader storage or uniform buffer object.
     AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER        = 1UL << 24,
-    /* The buffer will be used as a cube map texture */
+    /// The buffer will be used as a cube map texture.
     AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP               = 1UL << 25,
-    /* The buffer contains a complete mipmap hierarchy */
+    /// The buffer contains a complete mipmap hierarchy.
     AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE        = 1UL << 26,
 
     AHARDWAREBUFFER_USAGE_VENDOR_0  = 1ULL << 28,
@@ -182,15 +193,19 @@
     AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63,
 };
 
+/**
+ * Buffer description. Used for allocating new buffers and querying parameters
+ * of existing ones.
+ */
 typedef struct AHardwareBuffer_Desc {
-    uint32_t    width;      // width in pixels
-    uint32_t    height;     // height in pixels
-    uint32_t    layers;     // number of images
-    uint32_t    format;     // One of AHARDWAREBUFFER_FORMAT_*
-    uint64_t    usage;      // Combination of AHARDWAREBUFFER_USAGE_*
-    uint32_t    stride;     // Stride in pixels, ignored for AHardwareBuffer_allocate()
-    uint32_t    rfu0;       // Initialize to zero, reserved for future use
-    uint64_t    rfu1;       // Initialize to zero, reserved for future use
+    uint32_t    width;      ///< Width in pixels.
+    uint32_t    height;     ///< Height in pixels.
+    uint32_t    layers;     ///< Number of images in an image array.
+    uint32_t    format;     ///< One of AHARDWAREBUFFER_FORMAT_*
+    uint64_t    usage;      ///< Combination of AHARDWAREBUFFER_USAGE_*
+    uint32_t    stride;     ///< Row stride in pixels, ignored for AHardwareBuffer_allocate()
+    uint32_t    rfu0;       ///< Initialize to zero, reserved for future use.
+    uint64_t    rfu1;       ///< Initialize to zero, reserved for future use.
 } AHardwareBuffer_Desc;
 
 typedef struct AHardwareBuffer AHardwareBuffer;
@@ -199,8 +214,8 @@
  * Allocates a buffer that backs an AHardwareBuffer using the passed
  * AHardwareBuffer_Desc.
  *
- * Returns NO_ERROR on success, or an error number of the allocation fails for
- * any reason.
+ * \return NO_ERROR on success, or an error number of the allocation fails for
+ * any reason. The returned buffer has a reference count of 1.
  */
 int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc,
         AHardwareBuffer** outBuffer);
@@ -223,7 +238,7 @@
 void AHardwareBuffer_describe(const AHardwareBuffer* buffer,
         AHardwareBuffer_Desc* outDesc);
 
-/*
+/**
  * Lock the AHardwareBuffer for reading or writing, depending on the usage flags
  * passed.  This call may block if the hardware needs to finish rendering or if
  * CPU caches need to be synchronized, or possibly for other implementation-
@@ -231,16 +246,16 @@
  * descriptor that will be signaled when the buffer is locked, otherwise the
  * caller will block until the buffer is available.
  *
- * If rect is not NULL, the caller promises to modify only data in the area
+ * If \a rect is not NULL, the caller promises to modify only data in the area
  * specified by rect. If rect is NULL, the caller may modify the contents of the
  * entire buffer.
  *
  * The content of the buffer outside of the specified rect is NOT modified
  * by this call.
  *
- * The buffer usage may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set, then
- * outVirtualAddress is filled with the address of the buffer in virtual memory,
- * otherwise this function will fail.
+ * The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set,
+ * then outVirtualAddress is filled with the address of the buffer in virtual
+ * memory.
  *
  * THREADING CONSIDERATIONS:
  *
@@ -252,38 +267,38 @@
  * may return an error or leave the buffer's content into an indeterminate
  * state.
  *
- * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL or if the usage
+ * \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL or if the usage
  * flags are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or an error
  * number of the lock fails for any reason.
  */
 int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage,
         int32_t fence, const ARect* rect, void** outVirtualAddress);
 
-/*
+/**
  * Unlock the AHardwareBuffer; must be called after all changes to the buffer
  * are completed by the caller. If fence is not NULL then it will be set to a
  * file descriptor that is signaled when all pending work on the buffer is
  * completed. The caller is responsible for closing the fence when it is no
  * longer needed.
  *
- * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
- * number of the lock fails for any reason.
+ * \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL, or an error
+ * number if the unlock fails for any reason.
  */
 int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence);
 
-/*
+/**
  * Send the AHardwareBuffer to an AF_UNIX socket.
  *
- * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
- * number of the lock fails for any reason.
+ * \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL, or an error
+ * number if the operation fails for any reason.
  */
 int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd);
 
-/*
+/**
  * Receive the AHardwareBuffer from an AF_UNIX socket.
  *
- * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
- * number of the lock fails for any reason.
+ * \return NO_ERROR on success, BAD_VALUE if \a outBuffer is NULL, or an error
+ * number if the operation fails for any reason.
  */
 int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer);
 
diff --git a/libs/nativewindow/include/android/native_window.h b/libs/nativewindow/include/android/native_window.h
index f2d6f7a..d5e5e9d 100644
--- a/libs/nativewindow/include/android/native_window.h
+++ b/libs/nativewindow/include/android/native_window.h
@@ -85,23 +85,23 @@
  * A pointer can be obtained using {@link ANativeWindow_lock()}.
  */
 typedef struct ANativeWindow_Buffer {
-    // The number of pixels that are show horizontally.
+    /// The number of pixels that are shown horizontally.
     int32_t width;
 
-    // The number of pixels that are shown vertically.
+    /// The number of pixels that are shown vertically.
     int32_t height;
 
-    // The number of *pixels* that a line in the buffer takes in
-    // memory. This may be >= width.
+    /// The number of *pixels* that a line in the buffer takes in
+    /// memory. This may be >= width.
     int32_t stride;
 
-    // The format of the buffer. One of AHARDWAREBUFFER_FORMAT_*
+    /// The format of the buffer. One of AHARDWAREBUFFER_FORMAT_*
     int32_t format;
 
-    // The actual bits.
+    /// The actual bits.
     void* bits;
 
-    // Do not touch.
+    /// Do not touch.
     uint32_t reserved[6];
 } ANativeWindow_Buffer;