From 25461290ea1c0d339bcc89df4440cfdfb8897a07 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Wed, 24 Jun 2020 16:20:32 +0200
Subject: spec: Document name to id directives

---
 spec/if/rtems/region/ident.yml | 39 ++++++++++++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 7 deletions(-)

(limited to 'spec/if/rtems/region')

diff --git a/spec/if/rtems/region/ident.yml b/spec/if/rtems/region/ident.yml
index 40238e6b..ca0bf9b6 100644
--- a/spec/if/rtems/region/ident.yml
+++ b/spec/if/rtems/region/ident.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Identifies a region object by the specified object name.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -11,7 +12,9 @@ definition:
     - ${../types/id:/name} *${.:/params[1]/name}
     return: ${../status/code:/name}
   variants: []
-description: null
+description: |
+  This directive obtains the region identifier associated with the region name
+  specified in ``${.:/params[0]/name}``.
 enabled-by: true
 interface-type: function
 links:
@@ -20,15 +23,37 @@ links:
 - role: interface-ingroup
   uid: /groups/api/classic/region
 name: rtems_region_ident
-notes: null
+notes: |
+  If the region name is not unique, then the region identifier will match the
+  first region with that name in the search order.  However, this region
+  identifier is not guaranteed to correspond to the desired region.  The region
+  identifier is used with other region related directives to access the region.
+
+  The objects are searched from lowest to the highest index.  Only the local
+  node is searched.
 params:
-- description: '%'
+- description: is the object name to look up.
   dir: null
   name: name
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to an object identifier variable.  The object identifier of
+    an object with the specified name will be stored in this variable, in case
+    of a successful operation.
+  dir: out
   name: id
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../status/successful:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/if/c/null:/name}.
+    value: ${../status/invalid-address:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was 0.
+    value: ${../status/invalid-name:/name}
+  - description: |
+      There was no object with the specified name on the local node.
+    value: ${../status/invalid-name:/name}
 type: interface
-- 
cgit v1.2.3