Improved return value docs and samples

Details:

* Added 'changed' and 'msg' fields to the documented RETURNS string.

* 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.

* Added samples in most cases.

* This fixed errors in the described structure of return data for the
  following modules and result elements:
  - zhmc_adapter: 'ports' was described as a dict but is a list. Fixed
    description.
  - zhmc_cpc: 'adapters', 'partitions' and 'storage-groups' were described as
    dicts but are lists. Fixed description.
  - zhmc_storage_group: 'cpc-name' and 'cpc' were described but not
    implemented. Removed from description.
  - zhmc_user: 'user-pattern', 'password-rule', and 'ldap-server-definition'
    were missing from description. Added to description.
    Also, 'default-group-name' was described but is not implemented yet.
    Removed from description.

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

docs/changes.html

@@ -204,6 +204,9 @@ <h2>Version 1.0.0-dev1<a class="headerlink" href="#version-1-0-0-dev1" title="Pe
 <li><p>Fixed AttributeError when using the zhmc_adapter module to create a
 HiperSockets adapter. (see issue #141)</p></li>
 <li><p>Fixed ParameterError raised when creating NICs on CNA adapter ports.</p></li>
+<li><p>Docs: In the description of the module return data, added samples and
+fixed errors in the described structure of return data for the modules
+<cite>zhmc_adapter</cite>, <cite>zhmc_cpc</cite>, <cite>zhmc_storage_group</cite> and <cite>zhmc_user</cite>.</p></li>
 </ul>
 <p><strong>Enhancements:</strong></p>
 <ul class="simple">

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 of the adapter, 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 of the port, as described for the data model of the ‘Network Port’ or ‘Storage Port’ element object 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>
 </dl>
 </dd>

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">
@@ -264,51 +264,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 of the CPC, 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>

docs/modules/zhmc_crypto_attachment.html

@@ -228,15 +228,15 @@ <h2><a class="toc-backref" href="#id3">Parameters</a><a class="headerlink" href=
 <li><p><code class="docutils literal notranslate"><span class="pre">facts</span></code>: Does not change anything on the attachment and returns the crypto configuration of the partition.</p></li>
 </ul>
 </dd>
-<dt>adapter_count (False, int, -1)</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attach</span></code>: The number of crypto adapters the partition needs to have attached. The special value -1 means all adapters of the desired crypto type in the CPC. The <code class="docutils literal notranslate"><span class="pre">adapter_names</span></code> and <code class="docutils literal notranslate"><span class="pre">adapter_count</span></code> parameters are mutually exclusive; if neither is specified the default for <code class="docutils literal notranslate"><span class="pre">adapter_count</span></code> applies.</p>
+<dt>adapter_count (False, int, -1)</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attached</span></code>: The number of crypto adapters the partition needs to have attached. The special value -1 means all adapters of the desired crypto type in the CPC. The <code class="docutils literal notranslate"><span class="pre">adapter_names</span></code> and <code class="docutils literal notranslate"><span class="pre">adapter_count</span></code> parameters are mutually exclusive; if neither is specified the default for <code class="docutils literal notranslate"><span class="pre">adapter_count</span></code> applies.</p>
 </dd>
-<dt>adapter_names (False, list, [])</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attach</span></code>: The names of the crypto adapters the partition needs to have attached. The <code class="docutils literal notranslate"><span class="pre">adapter_names</span></code> and <code class="docutils literal notranslate"><span class="pre">adapter_count</span></code> parameters are mutually exclusive; if neither is specified the default for <code class="docutils literal notranslate"><span class="pre">adapter_count</span></code> applies.</p>
+<dt>adapter_names (False, list, [])</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attached</span></code>: The names of the crypto adapters the partition needs to have attached. The <code class="docutils literal notranslate"><span class="pre">adapter_names</span></code> and <code class="docutils literal notranslate"><span class="pre">adapter_count</span></code> parameters are mutually exclusive; if neither is specified the default for <code class="docutils literal notranslate"><span class="pre">adapter_count</span></code> applies.</p>
 </dd>
-<dt>domain_range (False, list, [0, -1])</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attach</span></code>: The domain range the partition needs to have attached, as a tuple of integers (min, max) that specify the inclusive range of domain index numbers. Other domains attached to the partition remain unchanged. The special value -1 for the max item means the maximum supported domain index number.</p>
+<dt>domain_range (False, list, [0, -1])</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attached</span></code>: The domain range the partition needs to have attached, as a tuple of integers (min, max) that specify the inclusive range of domain index numbers. Other domains attached to the partition remain unchanged. The special value -1 for the max item means the maximum supported domain index number.</p>
 </dd>
-<dt>access_mode (False, str, usage)</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attach</span></code>: The access mode in which the crypto domains specified in <code class="docutils literal notranslate"><span class="pre">domain_range</span></code> need to be attached.</p>
+<dt>access_mode (False, str, usage)</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attached</span></code>: The access mode in which the crypto domains specified in <code class="docutils literal notranslate"><span class="pre">domain_range</span></code> need to be attached.</p>
 </dd>
-<dt>crypto_type (False, str, ep11)</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attach</span></code>: The crypto type of the crypto adapters that will be considered for attaching.</p>
+<dt>crypto_type (False, str, ep11)</dt><dd><p>Only for <code class="docutils literal notranslate"><span class="pre">state=attached</span></code>: The crypto type of the crypto adapters that will be considered for attaching.</p>
 </dd>
 <dt>log_file (False, str, None)</dt><dd><p>File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger.</p>
 </dd>
@@ -312,17 +312,29 @@ <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>crypto_configuration (success, dict, )</dt><dd><p>For <code class="docutils literal notranslate"><span class="pre">state=detached|attached|facts</span></code>, the crypto configuration of the partition after the changes performed by the module.</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>changes (success, dict, )</dt><dd><p>The changes that were performed by the module.</p>
+<dl class="simple">
+<dt>added-adapters (, list, )</dt><dd><p>Names of the adapters that were added to the partition</p>
+</dd>
+<dt>added-domains (, list, )</dt><dd><p>Domain index numbers of the crypto domains that were added to the partition</p>
+</dd>
+</dl>
+</dd>
+<dt>crypto_configuration (success, dict, {‘CSPF1’: {‘adapters’: {‘CRYP00’: {‘adapter-family’: ‘crypto’, ‘adapter-id’: ‘118’, ‘card-location’: ‘A14B-LG09’, ‘class’: ‘adapter’, ‘crypto-number’: 0, ‘crypto-type’: ‘ep11-coprocessor’, ‘description’: ‘’, ‘detected-card-type’: ‘crypto-express-6s’, ‘name’: ‘CRYP00’, ‘object-id’: ‘e1274d16-e578-11e8-a87c-00106f239c31’, ‘object-uri’: ‘/api/adapters/e1274d16-e578-11e8-a87c-00106f239c31’, ‘parent’: ‘/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7’, ‘physical-channel-status’: ‘operating’, ‘state’: ‘online’, ‘status’: ‘active’, ‘tke-commands-enabled’: True, ‘type’: ‘crypto’, ‘udx-loaded’: False}}, ‘domain_config’: {‘10’: ‘usage’, ‘11’: ‘usage’}, ‘control_domains’: [], ‘usage_domains’: [10, 11]}})</dt><dd><p>The crypto configuration of the partition after the changes performed by the module.</p>
 <dl>
 <dt>{name} (, dict, )</dt><dd><p>Partition name</p>
 <dl>
-<dt>adapters (, dict, )</dt><dd><p>Attached adapters</p>
+<dt>adapters (, dict, )</dt><dd><p>Attached crypto adapters</p>
 <dl>
 <dt>{name} (, dict, )</dt><dd><p>Adapter name</p>
 <dl class="simple">
 <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 of the adapter, 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>
 </dl>
 </dd>
@@ -346,14 +358,6 @@ <h2><a class="toc-backref" href="#id5">Return Values</a><a class="headerlink" hr
 </dd>
 </dl>
 </dd>
-<dt>changes (success, dict, )</dt><dd><p>For <code class="docutils literal notranslate"><span class="pre">state=detached|attached|facts</span></code>, a dictionary with the changes performed.</p>
-<dl class="simple">
-<dt>added-adapters (, list, )</dt><dd><p>Names of the adapters that were added to the partition</p>
-</dd>
-<dt>added-domains (, list, )</dt><dd><p>Domain index numbers of the crypto domains that were added to the partition</p>
-</dd>
-</dl>
-</dd>
 </dl>
 </div>
 <div class="section" id="status">