Improve disposables docstrings

For: QubesOS/qubes-doc#1554
For: QubesOS/qubes-issues#1512

Author: ben-grande

linux/aux-tools/preload-dispvm

@@ -13,6 +13,11 @@ import qubesadmin
 
 
 def get_preload_max(qube) -> int | None:
+    """
+    Get the ``preload-dispvm-max`` feature as an integer.
+
+    :param qubes.vm.qubes.QubesVM qube: Qube to query the feature from.
+    """
     value = qube.features.get("preload-dispvm-max", None)
     return int(value) if value else value
 

qubes/api/internal.py

@@ -261,8 +261,6 @@ async def vm_volume_import_end(self, untrusted_payload):
     async def suspend_pre(self):
         """
         Method called before host system goes to sleep.
-
-        :return:
         """
 
         preload_templates = qubes.vm.dispvm.get_preload_templates(self.app)
@@ -346,8 +344,6 @@ async def suspend_pre(self):
     async def suspend_post(self):
         """
         Method called after host system wake up from sleep.
-
-        :return:
         """
 
         # Reload list of previously paused qubes before suspending

qubes/app.py

@@ -1636,6 +1636,12 @@ def _domain_event_callback(self, _conn, domain, event, _detail, _opaque):
 
     @qubes.events.handler("domain-pre-delete")
     def on_domain_pre_deleted(self, event, vm):
+        """
+        Forbid deleting qube if it is a dependency of another qube.
+
+        :param str event: Event which was fired.
+        :param qubes.vm.QubesVM name: Qube name.
+        """
         # pylint: disable=unused-argument
         for obj in itertools.chain(self.domains, (self,)):
             if obj is vm:
@@ -1738,6 +1744,21 @@ def on_property_set_default_netvm(
     def on_property_set_default_dispvm(
         self, event, name, newvalue=None, oldvalue=None
     ):
+        """
+        When system's default_dispvm is (re)set, alert every domain that has
+        the default value.
+
+        If there is a difference between the maximum number of preloaded
+        disposables configured globally and on the new and old setting, adapt
+        it to match the current scenario.
+
+        :param str event: Event which was fired.
+        :param str name: Property name.
+        :param qubes.vm.mix.dvmtemplate.DVMTemplateMixin newvalue: New value \
+            of the property.
+        :param qubes.vm.mix.dvmtemplate.DVMTemplateMixin oldvalue: Old value \
+            of the property.
+        """
         # pylint: disable=unused-argument
         for vm in self.domains:
             if hasattr(vm, "default_dispvm") and vm.property_is_default(

qubes/vm/adminvm.py

@@ -116,6 +116,9 @@ def xid(self) -> int:
 
         .. seealso:
            :py:attr:`qubes.vm.qubesvm.QubesVM.xid`
+
+        :return: 0
+        :rtype: int
         """
         return 0
 
@@ -351,17 +354,33 @@ async def run_service_for_stdio(self, *args, input=None, **kwargs):
     @qubes.events.handler("domain-feature-pre-set:preload-dispvm-threshold")
     def on_feature_pre_set_preload_dispvm_threshold(
         self, event, feature, value, oldvalue=None
-    ):  # pylint: disable=unused-argument
+    ):
+        """
+        Before accepting the ``preload-dispvm-threshold`` feature, validate it.
+
+        :param str event: Event which was fired.
+        :param str feature: Feature name.
+        :param int value: New value of the feature.
+        :param int oldvalue: Old value of the feature.
+        """
+        # pylint: disable=unused-argument
         value = value or "0"
         if not value.isdigit():
             raise qubes.exc.QubesValueError(
                 "Invalid preload-dispvm-threshold value: not a digit"
             )
 
     @qubes.events.handler("domain-feature-delete:preload-dispvm-max")
-    def on_feature_delete_preload_dispvm_max(
-        self, event, feature
-    ):  # pylint: disable=unused-argument
+    def on_feature_delete_preload_dispvm_max(self, event, feature):
+        """
+        On deletion of the ``preload-dispvm-max`` feature, fire
+        ``domain-preload-dispvm-start`` event on the system's
+        ``default_dispvm``.
+
+        :param str event: Event which was fired.
+        :param str feature: Feature name.
+        """
+        # pylint: disable=unused-argument
         if not (appvm := getattr(self.app, "default_dispvm", None)):
             return
         reason = "global feature was deleted"
@@ -372,7 +391,16 @@ def on_feature_delete_preload_dispvm_max(
     @qubes.events.handler("domain-feature-pre-set:preload-dispvm-max")
     def on_feature_pre_set_preload_dispvm_max(
         self, event, feature, value, oldvalue=None
-    ):  # pylint: disable=unused-argument
+    ):
+        """
+        Before accepting the ``preload-dispvm-max`` feature, validate it.
+
+        :param str event: Event which was fired.
+        :param str feature: Feature name.
+        :param int value: New value of the feature.
+        :param int oldvalue: Old value of the feature.
+        """
+        # pylint: disable=unused-argument
         if value == oldvalue:
             return
         if not (appvm := getattr(self.app, "default_dispvm", None)):
@@ -388,7 +416,18 @@ def on_feature_pre_set_preload_dispvm_max(
     @qubes.events.handler("domain-feature-set:preload-dispvm-max")
     def on_feature_set_preload_dispvm_max(
         self, event, feature, value, oldvalue=None
-    ):  # pylint: disable=unused-argument
+    ):
+        """
+        After setting the ``preload-dispvm-max`` feature, fire
+        ``domain-preload-dispvm-start`` event on the system's
+        ``default_dispvm``.
+
+        :param str event: Event which was fired.
+        :param str feature: Feature name.
+        :param int value: New value of the feature.
+        :param int oldvalue: Old value of the feature.
+        """
+        # pylint: disable=unused-argument
         if value == oldvalue:
             return
         if not (appvm := getattr(self.app, "default_dispvm", None)):