Improved return value docs and samples

Details: * Made sure that the RETURNS doc string of all modules is in sync with the actual output, shows all artificial properties, shows all child resources, and for all resources shows a placeholder for remaining properties along with a link to the specific data model for that resource in the HMC API book. Also, added samples in most cases. * This fixed errors in the described structure of return data for the following resources: - CPC Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>
zhmcclient · Nov 20, 2020 · e0a0ef9 · e0a0ef9
1 parent 2d63bb0
commit e0a0ef9
Show file tree

Hide file tree

Showing 12 changed files with 451 additions and 210 deletions.
diff --git a/docs/modules/zhmc_adapter.html b/docs/modules/zhmc_adapter.html
@@ -316,24 +316,22 @@ <h2><a class="toc-backref" href="#id4">Examples</a><a class="headerlink" href="#
 <div class="section" id="return-values">
 <h2><a class="toc-backref" href="#id5">Return Values</a><a class="headerlink" href="#return-values" title="Permalink to this headline">¶</a></h2>
 <dl>
-<dt>cpc (success, dict, )</dt><dd><p>For <code class="docutils literal notranslate"><span class="pre">state=absent</span></code>, an empty dictionary.</p>
-<p>For <code class="docutils literal notranslate"><span class="pre">state=set|present|facts</span></code>, a dictionary with the properties of the adapter, including additional artificial properties as described below.</p>
+<dt>changed (always, bool, )</dt><dd><p>Indicates if any change has been made by the module. For <code class="docutils literal notranslate"><span class="pre">state=facts</span></code>, always will be false.</p>
+</dd>
+<dt>msg (failure, bool, )</dt><dd><p>An error message that describes the failure.</p>
+</dd>
+<dt>adapter (success, dict, {‘adapter-family’: ‘ficon’, ‘adapter-id’: ‘120’, ‘allowed-capacity’: 64, ‘card-location’: ‘A14B-D112-J.01’, ‘channel-path-id’: ‘09’, ‘class’: ‘adapter’, ‘configured-capacity’: 14, ‘description’: ‘’, ‘detected-card-type’: ‘ficon-express-16s-plus’, ‘maximum-total-capacity’: 254, ‘name’: ‘FCP_120_SAN1_02’, ‘object-id’: ‘dfb2147a-e578-11e8-a87c-00106f239c31’, ‘object-uri’: ‘/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31’, ‘parent’: ‘/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7’, ‘physical-channel-status’: ‘operating’, ‘port-count’: 1, ‘ports’: [{‘class’: ‘storage-port’, ‘description’: ‘’, ‘element-id’: ‘0’, ‘element-uri’: ‘/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31/storage-ports/0’, ‘fabric-id’: ‘100088947155A1E9’, ‘index’: 0, ‘name’: ‘Port 0’, ‘parent’: ‘/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31’}], ‘state’: ‘online’, ‘status’: ‘active’, ‘storage-port-uris’: [‘/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31/storage-ports/0’], ‘type’: ‘fcp’, ‘used-capacity’: 20})</dt><dd><p>For <code class="docutils literal notranslate"><span class="pre">state=absent</span></code>, an empty dictionary.</p>
+<p>For <code class="docutils literal notranslate"><span class="pre">state=set|present|facts</span></code>, the adapter and its ports.</p>
 <dl>
 <dt>name (, str, )</dt><dd><p>Adapter name</p>
 </dd>
-<dt>{property} (, any, )</dt><dd><p>Additional properties of the adapter, as described in the <a class="reference internal" href="../appendix.html#term-HMC-API"><span class="xref std std-term">HMC API</span></a> (using hyphens (-) in the property names).</p>
+<dt>{property} (, any, )</dt><dd><p>Additional properties as described for the data model of the ‘Adapter’ object in the <a class="reference internal" href="../appendix.html#term-HMC-API"><span class="xref std std-term">HMC API</span></a> book. The property names have hyphens (-) as described in that book.</p>
 </dd>
-<dt>ports (, dict, )</dt><dd><p>Artificial property for the ports of the adapter, with a subset of its properties.</p>
-<dl>
-<dt>{name} (, dict, )</dt><dd><p>Port name</p>
+<dt>ports (, list, )</dt><dd><p>Artificial property for the ports of the adapter.</p>
 <dl class="simple">
 <dt>name (, str, )</dt><dd><p>Port name</p>
 </dd>
-<dt>status (, str, )</dt><dd><p>Status of the port</p>
-</dd>
-<dt>element_uri (, str, )</dt><dd><p>Canonical URI of the port</p>
-</dd>
-</dl>
+<dt>{property} (, any, )</dt><dd><p>Additional properties as described for the data model of the ‘Network Port’ or ‘Storage Port’ object in the <a class="reference internal" href="../appendix.html#term-HMC-API"><span class="xref std std-term">HMC API</span></a> book. The property names have hyphens (-) as described in that book.</p>
 </dd>
 </dl>
 </dd>

diff --git a/docs/modules/zhmc_cpc.html b/docs/modules/zhmc_cpc.html
@@ -192,7 +192,7 @@
 </div>
 <div class="section" id="synopsis">
 <h2><a class="toc-backref" href="#id1">Synopsis</a><a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
-<p>Gather facts about a CPC (Z system), including its adapters and partitions.</p>
+<p>Gather facts about a CPC (Z system), including its adapters, partitions, and storage groups.</p>
 <p>Update the properties of a CPC.</p>
 </div>
 <div class="section" id="requirements">
@@ -265,51 +265,55 @@ <h2><a class="toc-backref" href="#id4">Examples</a><a class="headerlink" href="#
 <div class="section" id="return-values">
 <h2><a class="toc-backref" href="#id5">Return Values</a><a class="headerlink" href="#return-values" title="Permalink to this headline">¶</a></h2>
 <dl>
-<dt>cpc (success, dict, )</dt><dd><p>A dictionary with the properties of the CPC, including additional artificial properties as described below.</p>
+<dt>changed (always, bool, )</dt><dd><p>Indicates if any change has been made by the module. For <code class="docutils literal notranslate"><span class="pre">state=facts</span></code>, always will be false.</p>
+</dd>
+<dt>msg (failure, bool, )</dt><dd><p>An error message that describes the failure.</p>
+</dd>
+<dt>cpc (success, dict, {‘name’: ‘CPCA’, ‘{property}’: ‘… more properties … ‘, ‘adapters’: [{‘adapter-family’: ‘ficon’, ‘adapter-id’: ‘120’, ‘name’: ‘FCP_120_SAN1_02’, ‘object-uri’: ‘/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31’, ‘status’: ‘active’, ‘type’: ‘fcp’}, {‘adapter-family’: ‘osa’, ‘adapter-id’: ‘10c’, ‘name’: ‘OSM1’, ‘object-uri’: ‘/api/adapters/ddde026c-e578-11e8-a87c-00106f239c31’, ‘status’: ‘active’, ‘type’: ‘osm’}], ‘partitions’: [{‘name’: ‘PART1’, ‘object-uri’: ‘/api/partitions/c44338de-351b-11e9-9fbb-00106f239d19’, ‘status’: ‘stopped’, ‘type’: ‘linux’}, {‘name’: ‘PART2’, ‘object-uri’: ‘/api/partitions/6a46d18a-cf79-11e9-b447-00106f239d19’, ‘status’: ‘active’, ‘type’: ‘ssc’}], ‘storage-groups’: [{‘cpc-uri’: ‘/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7’, ‘fulfillment-state’: ‘complete’, ‘name’: ‘CPCA_SG_PART1’, ‘object-uri’: ‘/api/storage-groups/58e41a42-20a6-11e9-8dfc-00106f239c31’, ‘type’: ‘fcp’}, {‘cpc-uri’: ‘/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7’, ‘fulfillment-state’: ‘complete’, ‘name’: ‘CPCA_SG_PART2’, ‘object-uri’: ‘/api/storage-groups/4947c6d0-f433-11ea-8f73-00106f239d19’, ‘type’: ‘fcp’}]})</dt><dd><p>The CPC and its adapters, partitions, and storage groups.</p>
 <dl>
 <dt>name (, str, )</dt><dd><p>CPC name</p>
 </dd>
-<dt>{property} (, any, )</dt><dd><p>Additional properties of the CPC, as described in the <a class="reference internal" href="../appendix.html#term-HMC-API"><span class="xref std std-term">HMC API</span></a> (using hyphens (-) in the property names).</p>
+<dt>{property} (, any, )</dt><dd><p>Additional properties as described for the data model of the ‘CPC’ object in the <a class="reference internal" href="../appendix.html#term-HMC-API"><span class="xref std std-term">HMC API</span></a> book. The property names have hyphens (-) as described in that book.</p>
 </dd>
-<dt>partitions (, dict, )</dt><dd><p>Artificial property for the defined partitions of the CPC, with a subset of its properties.</p>
-<dl>
-<dt>{name} (, dict, )</dt><dd><p>Partition name</p>
+<dt>adapters (, list, )</dt><dd><p>The adapters of the CPC, with a subset of their properties. For details, see the <a class="reference internal" href="../appendix.html#term-HMC-API"><span class="xref std std-term">HMC API</span></a> book.</p>
 <dl class="simple">
-<dt>name (, str, )</dt><dd><p>Partition name</p>
+<dt>name (, str, )</dt><dd><p>Adapter name</p>
 </dd>
-<dt>status (, str, )</dt><dd><p>Status of the partition</p>
+<dt>object-uri (, str, )</dt><dd><p>Canonical URI of the adapter</p>
 </dd>
-<dt>object_uri (, str, )</dt><dd><p>Canonical URI of the partition</p>
+<dt>adapter-id (, str, )</dt><dd><p>Adapter ID (PCHID)</p>
 </dd>
-</dl>
+<dt>type (, str, )</dt><dd><p>Adapter type</p>
+</dd>
+<dt>adapter-family (, str, )</dt><dd><p>Adapter family</p>
+</dd>
+<dt>status (, str, )</dt><dd><p>Status of the adapter</p>
 </dd>
 </dl>
 </dd>
-<dt>adapters (, dict, )</dt><dd><p>Artificial property for the adapters of the CPC, with a subset of its properties.</p>
-<dl>
-<dt>{name} (, dict, )</dt><dd><p>Adapter name</p>
+<dt>partitions (, list, )</dt><dd><p>The defined partitions of the CPC, with a subset of their properties. For details, see the <a class="reference internal" href="../appendix.html#term-HMC-API"><span class="xref std std-term">HMC API</span></a> book.</p>
 <dl class="simple">
-<dt>name (, str, )</dt><dd><p>Adapter name</p>
+<dt>name (, str, )</dt><dd><p>Partition name</p>
 </dd>
-<dt>status (, str, )</dt><dd><p>Status of the adapter</p>
+<dt>object-uri (, str, )</dt><dd><p>Canonical URI of the partition</p>
 </dd>
-<dt>object_uri (, str, )</dt><dd><p>Canonical URI of the adapter</p>
+<dt>type (, str, )</dt><dd><p>Type of the partition</p>
 </dd>
-</dl>
+<dt>status (, str, )</dt><dd><p>Status of the partition</p>
 </dd>
 </dl>
 </dd>
-<dt>storage-groups (, dict, )</dt><dd><p>Artificial property for the storage groups associated with the CPC, with a subset of its properties.</p>
-<dl>
-<dt>{name} (, dict, )</dt><dd><p>Storage group name</p>
+<dt>storage-groups (, list, )</dt><dd><p>The storage groups associated with the CPC, with a subset of their properties. For details, see the <a class="reference internal" href="../appendix.html#term-HMC-API"><span class="xref std std-term">HMC API</span></a> book.</p>
 <dl class="simple">
 <dt>name (, str, )</dt><dd><p>Storage group name</p>
 </dd>
-<dt>fulfillment-status (, str, )</dt><dd><p>Fulfillment status of the storage group</p>
+<dt>object-uri (, str, )</dt><dd><p>Canonical URI of the storage group</p>
 </dd>
-<dt>object_uri (, str, )</dt><dd><p>Canonical URI of the storage group</p>
+<dt>type (, str, )</dt><dd><p>Storage group type</p>
 </dd>
-</dl>
+<dt>fulfillment-status (, str, )</dt><dd><p>Fulfillment status of the storage group</p>
+</dd>
+<dt>cpc-uri (, str, )</dt><dd><p>Canonical URI of the associated CPC</p>
 </dd>
 </dl>
 </dd>

diff --git a/docs/searchindex.js b/docs/searchindex.js
diff --git a/docs_source/modules/zhmc_adapter.rst b/docs_source/modules/zhmc_adapter.rst
@@ -178,39 +178,38 @@ Examples
 Return Values
 -------------
 
-cpc (success, dict, )
+changed (always, bool, )
+  Indicates if any change has been made by the module. For ``state=facts``, always will be false.
+
+
+msg (failure, bool, )
+  An error message that describes the failure.
+
+
+adapter (success, dict, {'adapter-family': 'ficon', 'adapter-id': '120', 'allowed-capacity': 64, 'card-location': 'A14B-D112-J.01', 'channel-path-id': '09', 'class': 'adapter', 'configured-capacity': 14, 'description': '', 'detected-card-type': 'ficon-express-16s-plus', 'maximum-total-capacity': 254, 'name': 'FCP_120_SAN1_02', 'object-id': 'dfb2147a-e578-11e8-a87c-00106f239c31', 'object-uri': '/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31', 'parent': '/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7', 'physical-channel-status': 'operating', 'port-count': 1, 'ports': [{'class': 'storage-port', 'description': '', 'element-id': '0', 'element-uri': '/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31/storage-ports/0', 'fabric-id': '100088947155A1E9', 'index': 0, 'name': 'Port 0', 'parent': '/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31'}], 'state': 'online', 'status': 'active', 'storage-port-uris': ['/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31/storage-ports/0'], 'type': 'fcp', 'used-capacity': 20})
   For ``state=absent``, an empty dictionary.
 
-  For ``state=set|present|facts``, a dictionary with the properties of the adapter, including additional artificial properties as described below.
+  For ``state=set|present|facts``, the adapter and its ports.
 
 
   name (, str, )
     Adapter name
 
 
   {property} (, any, )
-    Additional properties of the adapter, as described in the :term:`HMC API` (using hyphens (-) in the property names).
+    Additional properties as described for the data model of the 'Adapter' object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.
 
 
-  ports (, dict, )
-    Artificial property for the ports of the adapter, with a subset of its properties.
+  ports (, list, )
+    Artificial property for the ports of the adapter.
 
 
-    {name} (, dict, )
+    name (, str, )
       Port name
 
 
-      name (, str, )
-        Port name
-
-
-      status (, str, )
-        Status of the port
-
-
-      element_uri (, str, )
-        Canonical URI of the port
-
+    {property} (, any, )
+      Additional properties as described for the data model of the 'Network Port' or 'Storage Port' object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.
 
 
 

diff --git a/docs_source/modules/zhmc_cpc.rst b/docs_source/modules/zhmc_cpc.rst
@@ -12,7 +12,7 @@ zhmc_cpc -- Manages Z systems at the system level.
 Synopsis
 --------
 
-Gather facts about a CPC (Z system), including its adapters and partitions.
+Gather facts about a CPC (Z system), including its adapters, partitions, and storage groups.
 
 Update the properties of a CPC.
 
@@ -116,81 +116,98 @@ Examples
 Return Values
 -------------
 
-cpc (success, dict, )
-  A dictionary with the properties of the CPC, including additional artificial properties as described below.
+changed (always, bool, )
+  Indicates if any change has been made by the module. For ``state=facts``, always will be false.
+
+
+msg (failure, bool, )
+  An error message that describes the failure.
+
+
+cpc (success, dict, {'name': 'CPCA', '{property}': '... more properties ... ', 'adapters': [{'adapter-family': 'ficon', 'adapter-id': '120', 'name': 'FCP_120_SAN1_02', 'object-uri': '/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31', 'status': 'active', 'type': 'fcp'}, {'adapter-family': 'osa', 'adapter-id': '10c', 'name': 'OSM1', 'object-uri': '/api/adapters/ddde026c-e578-11e8-a87c-00106f239c31', 'status': 'active', 'type': 'osm'}], 'partitions': [{'name': 'PART1', 'object-uri': '/api/partitions/c44338de-351b-11e9-9fbb-00106f239d19', 'status': 'stopped', 'type': 'linux'}, {'name': 'PART2', 'object-uri': '/api/partitions/6a46d18a-cf79-11e9-b447-00106f239d19', 'status': 'active', 'type': 'ssc'}], 'storage-groups': [{'cpc-uri': '/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7', 'fulfillment-state': 'complete', 'name': 'CPCA_SG_PART1', 'object-uri': '/api/storage-groups/58e41a42-20a6-11e9-8dfc-00106f239c31', 'type': 'fcp'}, {'cpc-uri': '/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7', 'fulfillment-state': 'complete', 'name': 'CPCA_SG_PART2', 'object-uri': '/api/storage-groups/4947c6d0-f433-11ea-8f73-00106f239d19', 'type': 'fcp'}]})
+  The CPC and its adapters, partitions, and storage groups.
 
 
   name (, str, )
     CPC name
 
 
   {property} (, any, )
-    Additional properties of the CPC, as described in the :term:`HMC API` (using hyphens (-) in the property names).
+    Additional properties as described for the data model of the 'CPC' object in the :term:`HMC API` book. The property names have hyphens (-) as described in that book.
 
 
-  partitions (, dict, )
-    Artificial property for the defined partitions of the CPC, with a subset of its properties.
+  adapters (, list, )
+    The adapters of the CPC, with a subset of their properties. For details, see the :term:`HMC API` book.
 
 
-    {name} (, dict, )
-      Partition name
+    name (, str, )
+      Adapter name
 
 
-      name (, str, )
-        Partition name
+    object-uri (, str, )
+      Canonical URI of the adapter
 
 
-      status (, str, )
-        Status of the partition
+    adapter-id (, str, )
+      Adapter ID (PCHID)
 
 
-      object_uri (, str, )
-        Canonical URI of the partition
+    type (, str, )
+      Adapter type
 
 
+    adapter-family (, str, )
+      Adapter family
 
 
-  adapters (, dict, )
-    Artificial property for the adapters of the CPC, with a subset of its properties.
+    status (, str, )
+      Status of the adapter
 
 
-    {name} (, dict, )
-      Adapter name
+
+  partitions (, list, )
+    The defined partitions of the CPC, with a subset of their properties. For details, see the :term:`HMC API` book.
 
 
-      name (, str, )
-        Adapter name
+    name (, str, )
+      Partition name
 
 
-      status (, str, )
-        Status of the adapter
+    object-uri (, str, )
+      Canonical URI of the partition
 
 
-      object_uri (, str, )
-        Canonical URI of the adapter
+    type (, str, )
+      Type of the partition
 
 
+    status (, str, )
+      Status of the partition
 
 
-  storage-groups (, dict, )
-    Artificial property for the storage groups associated with the CPC, with a subset of its properties.
 
+  storage-groups (, list, )
+    The storage groups associated with the CPC, with a subset of their properties. For details, see the :term:`HMC API` book.
 
-    {name} (, dict, )
+
+    name (, str, )
       Storage group name
 
 
-      name (, str, )
-        Storage group name
+    object-uri (, str, )
+      Canonical URI of the storage group
+
 
+    type (, str, )
+      Storage group type
 
-      fulfillment-status (, str, )
-        Fulfillment status of the storage group
 
+    fulfillment-status (, str, )
+      Fulfillment status of the storage group
 
-      object_uri (, str, )
-        Canonical URI of the storage group
 
+    cpc-uri (, str, )
+      Canonical URI of the associated CPC