diff --git a/media/ndk/include/media/NdkImage.h b/media/ndk/include/media/NdkImage.h
index 99cf5d5..19df760 100644
--- a/media/ndk/include/media/NdkImage.h
+++ b/media/ndk/include/media/NdkImage.h
@@ -72,14 +72,15 @@
     AIMAGE_FORMAT_RGBA_8888         = 0x1,
 
     /**
-     * 32 bits RGBX format, 8 bits for each of the four channels.
+     * 32 bits RGBX format, 8 bits for each of the four channels.  The values
+     * of the alpha channel bits are ignored (image is assumed to be opaque).
      *
      * <p>
      * Corresponding formats:
      * <ul>
      * <li>AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM</li>
      * <li>Vulkan: VK_FORMAT_R8G8B8A8_UNORM</li>
-     * <li>OpenGL ES: GL_RGBA8</li>
+     * <li>OpenGL ES: GL_RGB8</li>
      * </ul>
      * </p>
      *
@@ -717,7 +718,7 @@
 
 #if __ANDROID_API__ >= 26
 
-/*
+/**
  * Return the image back the the system and delete the AImage object from memory asynchronously.
  *
  * <p>Similar to {@link AImage_delete}, do NOT use the image pointer after this method returns.
@@ -746,8 +747,9 @@
  * AHardwareBuffer_acquire} to acquire an extra reference, and call {@link AHardwareBuffer_release}
  * once it has finished using it in order to properly deallocate the underlying memory managed by
  * {@link AHardwareBuffer}. If the caller has acquired extra reference on an {@link AHardwareBuffer}
- * returned from this function, it must also listen to {@link onBufferFreed} callback to be
- * notified when the buffer is no longer used by {@link AImageReader}.</p>
+ * returned from this function, it must also register a listener using the function
+ * {@link AImageReader_setBufferRemovedListener} to be notified when the buffer is no longer used
+ * by {@link AImageReader}.</p>
  *
  * @param image the {@link AImage} of interest.
  * @param outBuffer The memory area pointed to by buffer will contain the acquired AHardwareBuffer
diff --git a/media/ndk/include/media/NdkImageReader.h b/media/ndk/include/media/NdkImageReader.h
index e3b99d0..571410b 100644
--- a/media/ndk/include/media/NdkImageReader.h
+++ b/media/ndk/include/media/NdkImageReader.h
@@ -256,7 +256,7 @@
 
 
 /**
- * The definition of {@link AImageReader} new image available callback.
+ * Signature of the callback which is called when a new image is available from {@link AImageReader}.
  *
  * @param context The optional application context provided by user in
  *                {@link AImageReader_setImageListener}.
@@ -265,11 +265,11 @@
 typedef void (*AImageReader_ImageCallback)(void* context, AImageReader* reader);
 
 typedef struct AImageReader_ImageListener {
-    /// optional application context.
+    /// Optional application context passed as the first parameter of the callback.
     void*                      context;
 
     /**
-     * This callback is called when there is a new image available for in the image reader's queue.
+     * This callback is called when there is a new image available in the image reader's queue.
      *
      * <p>The callback happens on one dedicated thread per {@link AImageReader} instance. It is okay
      * to use AImageReader_* and AImage_* methods within the callback. Note that it is possible that
@@ -285,11 +285,11 @@
 /**
  * Set the onImageAvailable listener of this image reader.
  *
- * <p>Note that calling this method will replace previously registered listeners.</p>
+ * Calling this method will replace previously registered listeners.
  *
  * @param reader The image reader of interest.
- * @param listener the {@link AImageReader_ImageListener} to be registered. Set this to NULL if
- *                 application no longer needs to listen to new images.
+ * @param listener The {@link AImageReader_ImageListener} to be registered. Set this to NULL if
+ *                 the application no longer needs to listen to new images.
  *
  * @return <ul>
  *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
@@ -406,7 +406,7 @@
 media_status_t AImageReader_acquireLatestImageAsync(
         AImageReader* reader, /*out*/AImage** image, /*out*/int* acquireFenceFd);
 /**
- * The definition of {@link AImageReader} buffer removed callback.
+ * Signature of the callback which is called when {@link AImageReader} is about to remove a buffer.
  *
  * @param context The optional application context provided by user in
  *                {@link AImageReader_setBufferRemovedListener}.
@@ -418,7 +418,7 @@
         AHardwareBuffer* buffer);
 
 typedef struct AImageReader_BufferRemovedListener {
-    /// optional application context.
+    /// Optional application context passed as the first parameter of the callback.
     void*                      context;
 
     /**