sr_disk: document non-obvious behavior of features to be reworked

Quite important to make sure we replace them properly (ie. either with
identical behavior, or with a more correct one when applicable).

Signed-off-by: Yann Dirson <[email protected]>

Author: ydirson

conftest.py

@@ -328,6 +328,12 @@ def local_sr_on_hostB1(hostB1):
 
 @pytest.fixture(scope='session')
 def sr_disk(pytestconfig, host):
+    """
+    Disk DEVICE NAME available on FIRST POOL MASTER.
+
+    Abort if not exactly one --sr_disk.  If --sr_disk=auto take any, else
+    return requested device (abort if not present).
+    """
     disks = pytestconfig.getoption("sr_disk")
     if len(disks) != 1:
         pytest.fail("This test requires exactly one --sr-disk parameter")
@@ -346,6 +352,12 @@ def sr_disk(pytestconfig, host):
 
 @pytest.fixture(scope='session')
 def sr_disk_4k(pytestconfig, host):
+    """
+    Disk DEVICE NAME with 4KB blocksize available on FIRST POOL MASTER.
+
+    Abort if not exactly one --sr_disk.  If --sr_disk=auto take any, else
+    return requested device (abort if not present).
+    """
     disks = pytestconfig.getoption("sr_disk_4k")
     if len(disks) != 1:
         pytest.fail("This test requires exactly one --sr-disks-4k parameter")
@@ -364,6 +376,12 @@ def sr_disk_4k(pytestconfig, host):
 
 @pytest.fixture(scope='session')
 def sr_disk_for_all_hosts(pytestconfig, request, host):
+    """
+    Disk DEVICE NAME available on all hosts of FIRST POOL.
+
+    Abort if not exactly one --sr_disk.  If --sr_disk=auto take any, else
+    return requested device (abort if not present).
+    """
     disks = pytestconfig.getoption("sr_disk")
     if len(disks) != 1:
         pytest.fail("This test requires exactly one --sr-disk parameter")
@@ -393,6 +411,14 @@ def sr_disk_for_all_hosts(pytestconfig, request, host):
 
 @pytest.fixture(scope='session')
 def sr_disks_for_all_hosts(pytestconfig, request, host):
+    """
+    List of disk DEVICE NAMES available on all hosts of FIRST POOL.
+
+    Abort if no --sr_disk.  If one --sr_disk=auto given, return names of all
+    "available" disk device occuring on all hosts in the pool and
+    IGNORE ALL OTHER --sr_disk; else return all devices on commandline (abort
+    if any is not present or not "available").
+    """
     disks = pytestconfig.getoption("sr_disk")
     assert len(disks) > 0, "This test requires at least one --sr-disk parameter"
     # Fetch available disks on the master host

tests/storage/linstor/conftest.py

@@ -13,6 +13,16 @@
 
 @pytest.fixture(scope='package')
 def lvm_disks(host, sr_disks_for_all_hosts, provisioning_type):
+    """
+    Common LVM PVs on which a LV is created on each host of the pool.
+
+    On each host in the pool, create PV on each of those disks whose
+    DEVICE NAME exists ACROSS THE WHOLE POOL. Then make a VG out of
+    all those, then a LV taking up the whole VG space.
+
+    Return the list of device node paths for that list of devices
+    used in all hosts.
+    """
     devices = [f"/dev/{disk}" for disk in sr_disks_for_all_hosts]
     hosts = host.pool.hosts