1 files changed, 29 insertions, 7 deletions
diff --git a/spec/rtems/part/if/return-buffer.yml b/spec/rtems/part/if/return-buffer.yml
index 6c5118a5..3878f14f 100644
--- a/spec/rtems/part/if/return-buffer.yml
+++ b/spec/rtems/part/if/return-buffer.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Returns a buffer to the specified partition.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -11,9 +12,12 @@ definition:
     - void *${.:/params[1]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive returns the buffer specified by ${.:/params[1]/name} to the
+  partition specified by ${.:/params[0]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- return buffer to partition
 interface-type: function
 links:
 - role: interface-placement
@@ -21,15 +25,33 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_partition_return_buffer
-notes: null
+notes: |
+  This directive will not cause the running task to be preempted.
+
+  Returning a buffer to a global partition which does not reside on the local
+  node will generate a request telling the remote node to return the buffer to
+  the specified partition.
+
+  Returning a buffer multiple times is an error.  It will corrupt the internal
+  state of the partition.
 params:
-- description: '%'
+- description: is the partition identifier.
   dir: null
   name: id
-- description: '%'
+- description: is the pointer to the buffer to return.
   dir: null
   name: buffer
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no partition with the specified identifier.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The buffer referenced by ``${.:/params[1]/name}`` was no in the specified
+      partition.
+    value: ${../../status/if/invalid-address:/name}
 type: interface