ANDROID: dma-heap: document the return values of the exported helpers

dma_heap_find(), dma_heap_buffer_alloc() and dma_heap_bufferfd_alloc() all
have a documented parameter list but no Return: section, so kernel-doc has
nothing to say about what a caller gets back.

Documentation/doc-guide/kernel-doc.rst asks for a Return: section on
functions that return a value, and scripts/kernel-doc -none -Wall
include/linux/dma-heap.h reports three "No description found for return
value" warnings before this change and none after it. The default warning
level is unaffected: the file is clean there both before and after.

The wording follows what the implementations in drivers/dma-buf/dma-heap.c
actually do:

  dma_heap_find()          returns the heap, or NULL when the name is not
                           registered
  dma_heap_buffer_alloc()  returns a dma_buf, or an ERR_PTR() on failure
  dma_heap_bufferfd_alloc() returns an fd, or a negative errno on failure

All three helpers are ANDROID-only and do not exist upstream, so there is
nothing to send to mainline for this.

No functional change.

Change-Id: I9b8aa342cdda421af018171ec96f1257d8dbd5bc
Signed-off-by: Hung-Chun Tseng <alan.tseng.cs@gmail.com>

include/linux/dma-heap.h

@@ -74,6 +74,9 @@ void dma_heap_put(struct dma_heap *heap);
  *
  * NOTE: dma_heaps returned from this function MUST be released
  * using dma_heap_put() when the user is done.
+ *
+ * Return: the dma_heap with the given name, or NULL if no such heap is
+ * registered.
  */
 struct dma_heap *dma_heap_find(const char *name);
 
@@ -85,6 +88,8 @@ struct dma_heap *dma_heap_find(const char *name);
  * @heap_flags:	flags to pass to the dma heap
  *
  * This is for internal dma-buf allocations only.
+ *
+ * Return: a dma_buf on success, or an ERR_PTR() encoded error on failure.
  */
 struct dma_buf *dma_heap_buffer_alloc(struct dma_heap *heap, size_t len,
 				      u32 fd_flags,
@@ -103,6 +108,9 @@ void dma_heap_buffer_free(struct dma_buf *);
  * @len:	size to allocate
  * @fd_flags:	flags to set on returned dma-buf fd
  * @heap_flags:	flags to pass to the dma heap
+ *
+ * Return: a dma-buf file descriptor on success, or a negative errno on
+ * failure.
  */
 int dma_heap_bufferfd_alloc(struct dma_heap *heap, size_t len,
 			    u32 fd_flags,