sharedmem.h: fix the docs.

The complaint was that the docs were vague. Unfortunately, the truth is
a bit of a mess, but that's all the more reason for us to document it
clearly.

Bug: https://github.com/android/ndk/issues/1127
Test: N/A
Change-Id: I3ba116d43bb99731e0bb0832118e0d58a6400ad0

1 files changed, 6 insertions, 3 deletions

diff --git a/include/android/sharedmem.h b/include/android/sharedmem.h
index 7f5177bde9..2aacf11ee4 100644
--- a/include/android/sharedmem.h
+++ b/include/android/sharedmem.h
@@ -21,7 +21,7 @@
 
 /**
  * @file sharedmem.h
- * @brief Shared memory buffers that can be shared across process.
+ * @brief Shared memory buffers that can be shared between processes.
  */
 
 #ifndef ANDROID_SHARED_MEMORY_H
@@ -61,11 +61,14 @@ extern "C" {
  *
  * Use close() to release the shared memory region.
  *
+ * Use {@link android.os.ParcelFileDescriptor} to pass the file descriptor to
+ * another process.
+ *
  * Available since API level 26.
  *
  * \param name an optional name.
  * \param size size of the shared memory region
- * \return file descriptor that denotes the shared memory; error code on failure.
+ * \return file descriptor that denotes the shared memory; -1 and sets errno on failure, or -EINVAL if the error is that size was 0.
  */
 int ASharedMemory_create(const char *name, size_t size) __INTRODUCED_IN(26);
 
@@ -109,7 +112,7 @@ size_t ASharedMemory_getSize(int fd) __INTRODUCED_IN(26);
  * \param fd   file descriptor of the shared memory region.
  * \param prot any bitwise-or'ed combination of PROT_READ, PROT_WRITE, PROT_EXEC denoting
  *             updated access. Note access can only be removed, but not added back.
- * \return 0 for success, error code on failure.
+ * \return 0 for success, -1 and sets errno on failure.
  */
 int ASharedMemory_setProt(int fd, int prot) __INTRODUCED_IN(26);