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, 32 insertions, 23 deletions

diff --git a/plugins/modules/vyos_l3_interfaces.py b/plugins/modules/vyos_l3_interfaces.py
index 0849c29..0d2a5da 100644
--- a/plugins/modules/vyos_l3_interfaces.py
+++ b/plugins/modules/vyos_l3_interfaces.py
@@ -31,21 +31,28 @@ from __future__ import absolute_import, division, print_function
 
 __metaclass__ = type
 
+ANSIBLE_METADATA = {
+    "metadata_version": "1.1",
+    "status": ["preview"],
+    "supported_by": "network",
+}
 
 DOCUMENTATION = """
+---
 module: vyos_l3_interfaces
-short_description: L3 interfaces resource module
+version_added: '1.0.0'
+short_description: Layer 3 interfaces resource module.
 description: This module manages the L3 interface attributes on VyOS network devices.
-version_added: 1.0.0
 notes:
-- Tested against VyOS 1.1.8 (helium).
+- Tested against VyOS 1.3.
 - This module works with connection C(ansible.netcommon.network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html).
 author:
-- Nilashish Chakraborty (@NilashishC)
 - Rohit Thakur (@rohitthakur2590)
+- Nilashish Chakraborty (@nilashishc)
 options:
   config:
-    description: The provided L3 interfaces configuration.
+    description:
+    - The provided L3 interfaces configuration.
     type: list
     elements: dict
     suboptions:
@@ -73,36 +80,38 @@ options:
           address:
             description:
             - IPv6 address of the interface.
+            - C(auto-config) to use SLAAC to chose an address.
             type: str
       vifs:
         description:
-        - Virtual sub-interfaces L3 configurations.
+        - List of virtual sub-interfaces (VIFs) of the interface.
         elements: dict
         type: list
         suboptions:
           vlan_id:
             description:
-            - Identifier for the virtual sub-interface.
+            - Identifier for the VIF.
             type: int
           ipv4:
             description:
-            - List of IPv4 addresses of the virtual interface.
+            - List of IPv4 addresses of the VIF.
             type: list
             elements: dict
             suboptions:
               address:
                 description:
-                - IPv4 address of the virtual interface.
+                - IPv4 address of the VIF.
                 type: str
           ipv6:
             description:
-            - List of IPv6 addresses of the virtual interface.
+            - List of IPv6 addresses of the VIF.
             type: list
             elements: dict
             suboptions:
               address:
                 description:
-                - IPv6 address of the virtual interface.
+                - IPv6 address of the virtual VIF
+                - C(auto-config) to use SLAAC to chose an address.
                 type: str
   running_config:
     description:
@@ -122,9 +131,9 @@ options:
     - replaced
     - overridden
     - deleted
-    - parsed
-    - gathered
     - rendered
+    - gathered
+    - parsed
     default: merged
 """
 EXAMPLES = """
@@ -163,7 +172,6 @@ EXAMPLES = """
               - address: '2001:db8:1400::3/38'
     state: merged
 
-
 # After state:
 # -------------
 #
@@ -216,7 +224,7 @@ EXAMPLES = """
 
       - name: eth3
         ipv6:
-          - address: 2001:db8::11/32
+          - address: '2001:db8::11/32'
     state: replaced
 
 # After state:
@@ -273,7 +281,6 @@ EXAMPLES = """
           - address: dhcpv6
     state: overridden
 
-
 # After state
 # ------------
 #
@@ -315,8 +322,7 @@ EXAMPLES = """
 # set interfaces ethernet eth3 vif 102 address '2001:db8:4000::3/34'
 # set interfaces ethernet eth3 vif 102 address '2001:db8:4000::2/34'
 
-- name: Delete L3 attributes of given interfaces (Note - This won't delete the interface
-    itself)
+- name: Delete L3 attributes of given interfaces (Note - This won't delete the interface itself)
   vyos.vyos.vyos_l3_interfaces:
     config:
       - name: eth1
@@ -515,24 +521,27 @@ EXAMPLES = """
 """
 RETURN = """
 before:
-  description: The configuration as structured data prior to module invocation.
+  description: The configuration prior to the module invocation.
   returned: always
   type: list
   sample: >
     The configuration returned will always be in the same format
-     of the parameters above.
+    of the parameters above.
 after:
-  description: The configuration as structured data after module completion.
+  description: The resulting configuration module invocation.
   returned: when changed
   type: list
   sample: >
     The configuration returned will always be in the same format
-     of the parameters above.
+    of the parameters above.
 commands:
   description: The set of commands pushed to the remote device.
   returned: always
   type: list
-  sample: ['set interfaces ethernet eth1 192.0.2.14/2', 'set interfaces ethernet eth3 vif 101 address 198.51.100.130/25']
+  sample:
+    - 'set interfaces ethernet eth1 192.0.2.14/2'
+    - 'set interfaces ethernet eth3 vif 101 address 198.51.100.130/25'
+
 """