Improved hscommon.gui docs

hscommon/gui/base.py

@@ -13,23 +13,42 @@ class NoopGUI:
     def __getattr__(self, func_name):
         return noop
 
-# A GUIObject is a cross-toolkit "model" representation of a GUI layer object, for example, a table.
-# It acts as a cross-toolkit interface to multiple what we call here a "view". That view is a
-# toolkit-specific controller to the actual view (an NSTableView, a QTableView, etc.).
-# In our GUIObject, we need a reference to that toolkit-specific controller because some actions,
-# have effects on it (for example, prompting it to refresh its data). The GUIObject is typically
-# instantiated before its "view", that is why we set it as None on init. However, the GUI
-# layer is supposed to set the view as soon as its toolkit-specific controller is instantiated.
-
-# When you subclass GUIObject, you will likely want to update its view on instantiation. That
-# is why we call self.view.refresh() in _view_updated(). If you need another type of action on
-# view instantiation, just override the method.
 class GUIObject:
+    """Cross-toolkit "model" representation of a GUI layer object.
+    
+    A ``GUIObject`` is a cross-toolkit "model" representation of a GUI layer object, for example, a
+    table. It acts as a cross-toolkit interface to multiple what we call here a :attr:`view`. That
+    view is a toolkit-specific controller to the actual view (an ``NSTableView``, a ``QTableView``,
+    etc.). In our GUIObject, we need a reference to that toolkit-specific controller because some
+    actions, have effects on it (for example, prompting it to refresh its data). The ``GUIObject``
+    is typically instantiated before its :attr:`view`, that is why we set it as ``None`` on init.
+    However, the GUI layer is supposed to set the view as soon as its toolkit-specific controller is
+    instantiated.
+
+    When you subclass ``GUIObject``, you will likely want to update its view on instantiation. That
+    is why we call ``self.view.refresh()`` in :meth:`_view_updated`. If you need another type of
+    action on view instantiation, just override the method.
+    
+    .. attribute:: view
+    
+        A reference to our toolkit-specific view controller. This view stats as ``None`` and has to
+        be set "manually". There's two times at which we set the view property: On initialization,
+        where we set the view that we'll use for our lifetime, and just before the view is
+        deallocated. We need to unset our view at that time to avoid calls to a deallocated instance
+        (which means a crash).
+        
+        To unset our view, we simple assign it to ``None``.
+    """
     def __init__(self):
         self._view = None
     
     def _view_updated(self):
-        pass #virtual
+        """(Virtual) Called after :attr:`view` has been set.
+        
+        Doing nothing by default, this method is called after :attr:`view` has been set (it isn't
+        called when it's unset, however). Use this for initialization code that requires a view
+        (which is often the whole of the initialization code).
+        """
     
     def has_view(self):
         return (self._view is not None) and (not isinstance(self._view, NoopGUI))
@@ -40,10 +59,6 @@ class GUIObject:
     
     @view.setter
     def view(self, value):
-        # There's two times at which we set the view property: On initialization, where we set the
-        # view that we'll use for your lifetime, and just before the view is deallocated. We need
-        # to unset our view at that time to avoid calls to a deallocated instance (which means a
-        # crash).
         if self._view is None:
             # Initial view assignment
             if value is None: