Document classes

qubesdbus/domain.py

@@ -18,6 +18,8 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+''' D-Bus Domain object '''
+
 import dbus.service
 
 import qubesdbus.service
@@ -33,6 +35,9 @@
 
 
 class Domain(qubesdbus.service.PropertiesObject):
+    ''' `Domain` is managed by `DomainManager1` and represents a domain. Its D-Bus
+        object path is `/org/qubes/DomainManager1/domains/QID`
+    '''
     def __init__(self, bus, bus_name, bus_path, data):
         # type: (SessionBus, BusName , str, Dict[Union[str,dbus.String], Any]) -> None
         self.properties = data

qubesdbus/domain_manager.py

@@ -17,6 +17,7 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+''' org.qubes.DomainManager1 Service '''
 
 from __future__ import absolute_import, print_function
 
@@ -46,6 +47,14 @@
 
 
 class DomainManager(PropertiesObject):
+    ''' The `DomainManager` is the equivalent to the `qubes.Qubes` object for
+        managing domains. Implements:
+            * `org.freedesktop.DBus.ObjectManager` interface for acquiring all the
+               domains.
+            * `org.freedesktop.DBus.Properties` for accessing `qubes.Qubes`
+               properties
+    '''
+
     def __init__(self, data, domains):
         # type: (Dict[dbus.String, Any], List[Dict[Union[str,dbus.String], Any]]) -> None
         super(DomainManager, self).__init__('DomainManager1', data)
@@ -64,7 +73,11 @@ def GetManagedObjects(self):
     @dbus.service.method(dbus_interface='org.qubes.DomainManager1',
                          in_signature='a{sv}b')
     def AddDomain(self, vm, execute=False):
-        # type: (Dict[dbus.String, Any], bool) -> bool
+        ''' Notify the `DomainManager` when a domain is added. This is
+            called by `QubesDbusProxy` when 'domain-create-on-disk' event
+            arrives from `core-admin`. UI programs which need to create an
+            actual vm should set `execute` to True.
+        ''' # type: (Dict[dbus.String, Any], bool) -> bool
         if execute:
             log.error('Creating domains via DBus is not implemented yet')
             return False
@@ -79,16 +92,22 @@ def AddDomain(self, vm, execute=False):
 
     @dbus.service.signal("org.qubes.DomainManager1", signature="so")
     def DomainAdded(self, _, object_path):
+        ''' This signal is emitted when a new domain is added '''
         self.log.debug("Emiting DomainAdded signal: %s", object_path)
 
     @dbus.service.signal("org.qubes.DomainManager1", signature="so")
     def DomainRemoved(self, _, object_path):
+        ''' This signal is emitted when a new domain is removed '''
         self.log.debug("Emiting DomainRemoved signal: %s", object_path)
 
     @dbus.service.method(dbus_interface='org.qubes.DomainManager1',
                          in_signature='ob', out_signature='b')
     def RemoveDomain(self, vm_dbus_path, execute=False):
-        # type: (dbus.ObjectPath, bool) -> bool
+        ''' Notify the `DomainManager` when a domain is removed. This is
+            called by `QubesDbusProxy` when 'domain-deleted' event
+            arrives from `core-admin`. UI programs which need to remove an
+            actual vm should set `execute` to True.
+        ''' # type: (dbus.ObjectPath, bool) -> bool
         if execute:
             log.error('Creating domains via DBus is not implemented yet')
             return False
@@ -106,8 +125,8 @@ def _proxify_domain(self, vm):
         return Domain(self.bus, self.bus_name, self.bus_path, vm)
 
 
-def main(args=None):
-    ''' Main function '''  # pylint: disable=unused-argument
+def main(args=None):  # pylint: disable=unused-argument
+    ''' Main function starting the DomainManager1 service. '''
     loop = GLib.MainLoop()
     app = qubes.Qubes()
     data = qubesdbus.serialize.qubes_data(app)

qubesdbus/labels.py

@@ -17,6 +17,7 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+''' org.qubes.Labels1 service '''
 
 from __future__ import absolute_import, print_function
 
@@ -37,6 +38,10 @@
 
 
 class Labels(DbusServiceObject):
+    ''' A `org.freedesktop.DBus.ObjectManager` interface implementation, for
+	acquiring all the labels.
+    '''
+
     def __init__(self, labels_data):
         super(Labels, self).__init__()
         self.labels = dbus.Array()
@@ -54,6 +59,10 @@ def GetManagedObjects(self):
 
 
 class Label(PropertiesObject):
+    ''' Represents a qubes label. Its D-Bus object path is
+	`org/qubes/Labels1/labels/COLORNAME`
+    '''
+
     def __init__(self, bus, bus_name, bus_path, data):
         bus_path = '/'.join([bus_path, 'labels', data['name']])
         name = data['name']