docs: Clarify the lifetime of AHardwareBuffer_toHardwareBuffer in docs. See
generated output in cl/320449087.
Bug: 140885254
Test: m ndk
Change-Id: I5b27dcedd5b0d20003b46c05c40a8c7c26dd9d28
diff --git a/include/android/hardware_buffer_jni.h b/include/android/hardware_buffer_jni.h
index 293e5ac..ae208a6 100644
--- a/include/android/hardware_buffer_jni.h
+++ b/include/android/hardware_buffer_jni.h
@@ -39,9 +39,9 @@
* Return the AHardwareBuffer wrapped by a Java HardwareBuffer object.
*
* This method does not acquire any additional reference to the AHardwareBuffer
- * that is returned. To keep the AHardwareBuffer live after the Java
- * HardwareBuffer object got garbage collected, be sure to use AHardwareBuffer_acquire()
- * to acquire an additional reference.
+ * that is returned. To keep the AHardwareBuffer alive after the Java
+ * HardwareBuffer object is closed, explicitly or by the garbage collector, be
+ * sure to use AHardwareBuffer_acquire() to acquire an additional reference.
*
* Available since API level 26.
*/
@@ -50,7 +50,18 @@
/**
* Return a new Java HardwareBuffer object that wraps the passed native
- * AHardwareBuffer object.
+ * AHardwareBuffer object. The Java HardwareBuffer will acquire a reference to
+ * the internal buffer and manage its lifetime. For example:
+ *
+ * <pre><code>
+ * AHardwareBuffer* buffer;
+ * AHardwareBuffer_allocate(..., &buffer); // `buffer` has reference count 1
+ * jobject java_result = AHardwareBuffer_toHardwareBuffer(buffer); // `buffer` has reference count 2.
+ * AHardwareBuffer_release(buffer); // `buffer` has reference count 1
+ * return result; // The underlying buffer is kept alive by `java_result` and
+ * // will be set to 0 when it is closed on the Java side with
+ * // HardwareBuffer::close().
+ * </code></pre>
*
* Available since API level 26.
*/