docs: Fix docstrings of xcp/net/ifrename for Sphinx-autodoc generation

tox.ini

@@ -119,9 +119,9 @@ commands    =
     coverage xml  -o {envlogdir}/coverage.xml  --fail-under {env:XCP_COVERAGE_MIN:78}
     coverage lcov -o {envlogdir}/coverage.lcov
     coverage html -d {envlogdir}/htmlcov
-    coverage html -d {envlogdir}/htmlcov-tests --fail-under {env:TESTS_COVERAGE_MIN:96} \
+    coverage html -d {envlogdir}/htmlcov-tests --fail-under {env:TESTS_COVERAGE_MIN:95} \
                       --include="tests/*"
-    diff-cover --compare-branch=origin/master --exclude xcp/dmv.py                    \
+    diff-cover --compare-branch=origin/master                                         \
       {env:PY3_DIFFCOVER_OPTIONS} --fail-under {env:DIFF_COVERAGE_MIN:92}             \
       --html-report  {envlogdir}/coverage-diff.html                                   \
                      {envlogdir}/coverage.xml

xcp/net/ifrename/logic.py

@@ -39,6 +39,10 @@
 [out] transactions
         list of string tuples as source and destination names for "ip link set
         name"
+
+Abbreviations used in this file:
+    kname: The kernel name of the network interface (the original name assigned by the kernel).
+    tname: The temporary name of the interface, used while renaming interfaces to avoid name conflicts.
 """
 
 from __future__ import unicode_literals
@@ -122,24 +126,32 @@ def __rename_nic(nic, name, transactions, cur_state):
         transactions.append((nic.kname, name))
 
 
-def rename_logic( static_rules,
-                  cur_state,
-                  last_state,
-                  old_state ):
+def rename_logic(static_rules, cur_state, last_state, old_state):
     """
     Core logic of renaming the current state based on the rules and past state.
+
     This function assumes all inputs have been suitably sanitised.
-    @param static_rules
+
+    Parameters
+    ----------
+    static_rules : list[MACPCI]
         List of MACPCI objects representing rules
-    @param cur_state
+    cur_state : list[MACPCI]
         List of MACPCI objects representing the current state
-    @param last_state
+    last_state : list[MACPCI]
         List of MACPCI objects representing the last boot state
-    @param old_state
+    old_state : list[MACPCI]
         List of MACPCI objects representing the old state
-    @returns List of tuples...
-    @throws AssertionError (Should not be thrown, but better to know about logic
-    errors if they occur)
+
+    Returns
+    -------
+    list
+        List of tuples representing name transactions.
+
+    Raises
+    ------
+    AssertionError
+        If the current state contains invalid entries.
     """
 
     transactions = []
@@ -365,26 +377,44 @@ def rename_logic( static_rules,
                                          util.niceformat(cur_state)))
     return transactions
 
-def rename( static_rules,
-            cur_state,
-            last_state,
-            old_state ):
+def rename(static_rules, cur_state, last_state, old_state):
     """
     Rename current state based on the rules and past state.
-    This function sanitises the input and delegates the renaming logic to
-    __rename.
-    @param static_rules
+
+    This function:
+    - Sanitises the input
+    - Delegates the renaming logic to rename_logic()
+
+    Parameters
+    ----------
+    static_rules : list[MACPCI]
         List of MACPCI objects representing rules
-    @param cur_state
+    cur_state : list[MACPCI]
         List of MACPCI objects representing the current state
-    @param last_state
+    last_state : list[MACPCI]
         List of MACPCI objects representing the last boot state
-    @param old_state
+    old_state : list[MACPCI]
         List of MACPCI objects representing the old state
 
-    @throws StaticRuleError, CurrentStateError, LastStateError, TypeError
-
-    @returns list of tuples of name changes required
+    Returns
+    -------
+    list
+        List of tuples of name changes required
+
+    Raises
+    ------
+    StaticRuleError
+        Raised if any of the following conditions are met:
+        - A static rule has a kernel name.
+        - A static rule has a tname not starting with 'eth'.
+        - Duplicate eth names are present in static rules.
+        - Duplicate MAC addresses are present in static rules.
+    CurrentStateError
+        If the current state contains invalid entries.
+    LastStateError
+        If the last state contains invalid entries.
+    TypeError
+        If any of the input lists contain objects that are not MACPCI instances.
     """
 
     if len(static_rules):

xcp/net/ifrename/static.py

@@ -25,17 +25,16 @@
 Object for manipulating static rules.
 
 Rules are of the form:
-  <target name>: <id method> = "value"
+    <target name>: <id method> = "value"
 
-target name must be in the form eth*
-id methods are:
-  mac: value should be the mac address of a device (e.g. DE:AD:C0:DE:00:00)
-  pci: value should be the pci bus location of the device, optionally with an index (e.g. 0000:01:01.1[0])
-  ppn: value should be the result of the biosdevname physical naming policy of a device (e.g. p1p1)
-  label: value should be the SMBios label of a device (for SMBios 2.6 or above)
-
-Any line starting with '#' is considered to be a comment
+    target name must be in the form eth*
+    id methods are:
+    - `mac`: value should be the MAC address of a device (e.g. DE:AD:C0:DE:00:00)
+    - `pci`: value should be the PCI bus location of the device, optionally with an index (e.g. 0000:01:01.1[0])
+    - `ppn`: value should be the result of the biosdevname physical naming policy of a device (e.g. p1p1)
+    - `label`: value should be the SMBIOS label of a device (for SMBIOS 2.6 or above)
 
+    Any line starting with '#' is considered to be a comment
 """
 
 from __future__ import unicode_literals
@@ -71,10 +70,10 @@
 
 # target name must be in the form eth*
 # id methods are:
-#   mac: value should be the mac address of a device (e.g. DE:AD:C0:DE:00:00)
-#   pci: value should be the pci bus location of the device (e.g. 0000:01:01.1[0])
+#   mac: value should be the MAC address of a device (e.g. DE:AD:C0:DE:00:00)
+#   pci: value should be the PCI bus location of the device (e.g. 0000:01:01.1[0])
 #   ppn: value should be the result of the biosdevname physical naming policy of a device (e.g. p1p1)
-#   label: value should be the SMBios label of a device (for SMBios 2.6 or above)
+#   label: value should be the SMBIOS label of a device (for SMBIOS 2.6 or above)
 
 """