T6910: fix documentation and argspecs are out of alignment (#358)

chore: update firewall_rules from module
fix: update firewall_global from resource model
chore: update to sync with resource module
chore: update README
fix: comment and formatting
fix: formatting issues
fix: missing imports
fix: import and metadata violations
fix: interface fixes
fix: move the arg spec comment
fix: update interface docs
fix: remove comments for non-RM versions
* T6910: fix documentation and argspecs
* T6910: docs: update per review
* T6910: docs: fix missing pipe

1 files changed, 62 insertions, 12 deletions

diff --git a/docs/vyos.vyos.vyos_interfaces_module.rst b/docs/vyos.vyos.vyos_interfaces_module.rst
index f5f6941b..24156270 100644
--- a/docs/vyos.vyos.vyos_interfaces_module.rst
+++ b/docs/vyos.vyos.vyos_interfaces_module.rst
@@ -5,10 +5,10 @@
 vyos.vyos.vyos_interfaces
 *************************
 
-**Interfaces resource module**
+**Manages interface attributes of VyOS network devices.**
 
 
-Version added: 1.0.0
+Version added: 2.9.0
 
 .. contents::
    :local:
@@ -47,7 +47,7 @@ Parameters
                 <td>
                 </td>
                 <td>
-                        <div>The provided interfaces configuration.</div>
+                        <div>The provided interface configuration.</div>
                 </td>
             </tr>
                                 <tr>
@@ -107,6 +107,7 @@ Parameters
                 <td>
                         <div>Administrative state of the interface.</div>
                         <div>Set the value to <code>true</code> to administratively enable the interface or <code>false</code> to disable it.</div>
+                        <div style="font-size: small; color: darkgreen"><br/>aliases: enable</div>
                 </td>
             </tr>
             <tr>
@@ -223,6 +224,7 @@ Parameters
                 <td>
                         <div>Administrative state of the virtual sub-interface.</div>
                         <div>Set the value to <code>true</code> to administratively enable the interface or <code>false</code> to disable it.</div>
+                        <div style="font-size: small; color: darkgreen"><br/>aliases: enable</div>
                 </td>
             </tr>
             <tr>
@@ -311,9 +313,8 @@ Notes
 -----
 
 .. note::
-   - Tested against VyOS 1.1.8 (helium).
+   - Tested against VyOS 1.3.8
    - This module works with connection ``ansible.netcommon.network_cli``. See `the VyOS OS Platform Options <../network/user_guide/platform_vyos.html>`_.
-   - The examples use the stdout_callback as yaml to produce task outputs.
 
 
 
@@ -1025,11 +1026,10 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
                 </td>
                 <td>when changed</td>
                 <td>
-                            <div>The configuration as structured data after module completion.</div>
+                            <div>The resulting configuration after module execution.</div>
                     <br/>
                         <div style="font-size: smaller"><b>Sample:</b></div>
-                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">The configuration returned will always be in the same format
-     of the parameters above.</div>
+                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">This output will always be in the same format as the module argspec.</div>
                 </td>
             </tr>
             <tr>
@@ -1041,13 +1041,12 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
                       <span style="color: purple">list</span>
                     </div>
                 </td>
-                <td>always</td>
+                <td>when <em>state</em> is <code>merged</code>, <code>replaced</code>, <code>overridden</code>, <code>deleted</code> or <code>purged</code></td>
                 <td>
-                            <div>The configuration as structured data prior to module invocation.</div>
+                            <div>The configuration prior to the module execution.</div>
                     <br/>
                         <div style="font-size: smaller"><b>Sample:</b></div>
-                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">The configuration returned will always be in the same format
-     of the parameters above.</div>
+                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">This output will always be in the same format as the module argspec.</div>
                 </td>
             </tr>
             <tr>
@@ -1067,6 +1066,57 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
                         <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[&#x27;set interfaces ethernet eth1 mtu 1200&#x27;, &#x27;set interfaces ethernet eth2 vif 100 description VIF 100&#x27;]</div>
                 </td>
             </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="return-"></div>
+                    <b>gathered</b>
+                    <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
+                    <div style="font-size: small">
+                      <span style="color: purple">list</span>
+                    </div>
+                </td>
+                <td>when <em>state</em> is <code>gathered</code></td>
+                <td>
+                            <div>Facts about the network resource gathered from the remote device as structured data.</div>
+                    <br/>
+                        <div style="font-size: smaller"><b>Sample:</b></div>
+                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">This output will always be in the same format as the module argspec.</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="return-"></div>
+                    <b>parsed</b>
+                    <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
+                    <div style="font-size: small">
+                      <span style="color: purple">list</span>
+                    </div>
+                </td>
+                <td>when <em>state</em> is <code>parsed</code></td>
+                <td>
+                            <div>The device native config provided in <em>running_config</em> option parsed into structured data as per module argspec.</div>
+                    <br/>
+                        <div style="font-size: smaller"><b>Sample:</b></div>
+                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">This output will always be in the same format as the module argspec.</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="return-"></div>
+                    <b>rendered</b>
+                    <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
+                    <div style="font-size: small">
+                      <span style="color: purple">list</span>
+                    </div>
+                </td>
+                <td>when <em>state</em> is <code>rendered</code></td>
+                <td>
+                            <div>The provided configuration in the task rendered in device-native format (offline).</div>
+                    <br/>
+                        <div style="font-size: smaller"><b>Sample:</b></div>
+                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[&#x27;set interfaces ethernet eth1 mtu 1200&#x27;, &#x27;set interfaces ethernet eth2 vif 100 description VIF 100&#x27;]</div>
+                </td>
+            </tr>
     </table>
     <br/><br/>