Merge f492838 into 67ea98b

zhmcclient · Nov 22, 2020 · d6cdf92 · d6cdf92
2 parents 67ea98b + f492838
commit d6cdf92
Show file tree

Hide file tree

Showing 36 changed files with 1,692 additions and 508 deletions.
diff --git a/docs/changes.html b/docs/changes.html
@@ -209,6 +209,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">

diff --git a/docs/modules/zhmc_adapter.html b/docs/modules/zhmc_adapter.html
@@ -355,36 +355,45 @@ <h2><a class="toc-backref" href="#id3">Examples</a><a class="headerlink" href="#
 <h2><a class="toc-backref" href="#id4">Return Values</a><a class="headerlink" href="#return-values" title="Permalink to this headline">¶</a></h2>
 <blockquote>
 <div><dl>
-<dt>cpc</dt><dd><blockquote>
+<dt>changed</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>
+<div class="line-block">
+<div class="line"><strong>returned</strong>: always</div>
+<div class="line"><strong>type</strong>: bool</div>
+</div>
+</dd>
+<dt>msg</dt><dd><p>An error message that describes the failure.</p>
+<div class="line-block">
+<div class="line"><strong>returned</strong>: failure</div>
+<div class="line"><strong>type</strong>: str</div>
+</div>
+</dd>
+<dt>adapter</dt><dd><blockquote>
 <div><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>
+<p>For <code class="docutils literal notranslate"><span class="pre">state=set|present|facts</span></code>, the adapter and its ports.</p>
 <div class="line-block">
 <div class="line"><strong>returned</strong>: success</div>
 <div class="line"><strong>type</strong>: dict</div>
 </div>
+<p><strong>sample</strong>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;adapter-family&quot;</span><span class="p">:</span> <span class="s2">&quot;ficon&quot;</span><span class="p">,</span> <span class="s2">&quot;adapter-id&quot;</span><span class="p">:</span> <span class="s2">&quot;120&quot;</span><span class="p">,</span> <span class="s2">&quot;allowed-capacity&quot;</span><span class="p">:</span> <span class="mi">64</span><span class="p">,</span> <span class="s2">&quot;card-location&quot;</span><span class="p">:</span> <span class="s2">&quot;A14B-D112-J.01&quot;</span><span class="p">,</span> <span class="s2">&quot;channel-path-id&quot;</span><span class="p">:</span> <span class="s2">&quot;09&quot;</span><span class="p">,</span> <span class="s2">&quot;class&quot;</span><span class="p">:</span> <span class="s2">&quot;adapter&quot;</span><span class="p">,</span> <span class="s2">&quot;configured-capacity&quot;</span><span class="p">:</span> <span class="mi">14</span><span class="p">,</span> <span class="s2">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span> <span class="s2">&quot;detected-card-type&quot;</span><span class="p">:</span> <span class="s2">&quot;ficon-express-16s-plus&quot;</span><span class="p">,</span> <span class="s2">&quot;maximum-total-capacity&quot;</span><span class="p">:</span> <span class="mi">254</span><span class="p">,</span> <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;FCP_120_SAN1_02&quot;</span><span class="p">,</span> <span class="s2">&quot;object-id&quot;</span><span class="p">:</span> <span class="s2">&quot;dfb2147a-e578-11e8-a87c-00106f239c31&quot;</span><span class="p">,</span> <span class="s2">&quot;object-uri&quot;</span><span class="p">:</span> <span class="s2">&quot;/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31&quot;</span><span class="p">,</span> <span class="s2">&quot;parent&quot;</span><span class="p">:</span> <span class="s2">&quot;/api/cpcs/66942455-4a14-3f99-8904-3e7ed5ca28d7&quot;</span><span class="p">,</span> <span class="s2">&quot;physical-channel-status&quot;</span><span class="p">:</span> <span class="s2">&quot;operating&quot;</span><span class="p">,</span> <span class="s2">&quot;port-count&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;ports&quot;</span><span class="p">:</span> <span class="p">[{</span><span class="s2">&quot;class&quot;</span><span class="p">:</span> <span class="s2">&quot;storage-port&quot;</span><span class="p">,</span> <span class="s2">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span> <span class="s2">&quot;element-id&quot;</span><span class="p">:</span> <span class="s2">&quot;0&quot;</span><span class="p">,</span> <span class="s2">&quot;element-uri&quot;</span><span class="p">:</span> <span class="s2">&quot;/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31/storage-ports/0&quot;</span><span class="p">,</span> <span class="s2">&quot;fabric-id&quot;</span><span class="p">:</span> <span class="s2">&quot;100088947155A1E9&quot;</span><span class="p">,</span> <span class="s2">&quot;index&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Port 0&quot;</span><span class="p">,</span> <span class="s2">&quot;parent&quot;</span><span class="p">:</span> <span class="s2">&quot;/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31&quot;</span><span class="p">}],</span> <span class="s2">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;online&quot;</span><span class="p">,</span> <span class="s2">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;active&quot;</span><span class="p">,</span> <span class="s2">&quot;storage-port-uris&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;/api/adapters/dfb2147a-e578-11e8-a87c-00106f239c31/storage-ports/0&quot;</span><span class="p">],</span> <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;fcp&quot;</span><span class="p">,</span> <span class="s2">&quot;used-capacity&quot;</span><span class="p">:</span> <span class="mi">20</span><span class="p">}</span>
+</pre></div>
+</div>
 </div></blockquote>
 <dl>
 <dt>name</dt><dd><p>Adapter name</p>
 <div class="line-block">
 <div class="line"><strong>type</strong>: str</div>
 </div>
 </dd>
-<dt>{property}</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}</dt><dd><p>Additional properties of the adapter, as described in 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>
 <div class="line-block">
 <div class="line"><strong>type</strong>:</div>
 </div>
 </dd>
 <dt>ports</dt><dd><blockquote>
-<div><p>Artificial property for the ports of the adapter, with a subset of its properties.</p>
+<div><p>Artificial property for the ports of the adapter.</p>
 <div class="line-block">
-<div class="line"><strong>type</strong>: dict</div>
-</div>
-</div></blockquote>
-<dl>
-<dt>{name}</dt><dd><blockquote>
-<div><p>Port name</p>
-<div class="line-block">
-<div class="line"><strong>type</strong>: dict</div>
+<div class="line"><strong>type</strong>: list</div>
 </div>
 </div></blockquote>
 <dl>
@@ -393,23 +402,16 @@ <h2><a class="toc-backref" href="#id4">Return Values</a><a class="headerlink" hr
 <div class="line"><strong>type</strong>: str</div>
 </div>
 </dd>
-<dt>status</dt><dd><p>Status of the port</p>
+<dt>{property}</dt><dd><p>Additional properties of the port, as described in 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>
 <div class="line-block">
-<div class="line"><strong>type</strong>: str</div>
-</div>
-</dd>
-<dt>element_uri</dt><dd><p>Canonical URI of the port</p>
-<div class="line-block">
-<div class="line"><strong>type</strong>: str</div>
+<div class="line"><strong>type</strong>:</div>
 </div>
 </dd>
 </dl>
 </dd>
 </dl>
 </dd>
 </dl>
-</dd>
-</dl>
 </div></blockquote>
 </div>
 </div>