Add more docstrings for the new UI.

2 files changed, 33 insertions, 3 deletions

diff --git a/pyanaconda/threads.py b/pyanaconda/threads.py
index 7fed48a1e..f83bb0909 100644
--- a/pyanaconda/threads.py
+++ b/pyanaconda/threads.py
@@ -64,6 +64,14 @@ class ThreadManager(object):
         return self._objs.get(name)
 
 class AnacondaThread(threading.Thread):
+    """A threading.Thread subclass that exists only for a couple purposes:
+
+       (1) Make exceptions that happen in a thread invoke our exception handling
+           code as well.  Otherwise, threads will silently die and we are doing
+           a lot of complicated code in them now.
+
+       (2) Remove themselves from the thread manager when completed.
+    """
     def run(self, *args, **kwargs):
         # http://bugs.python.org/issue1230540#msg25696
         import sys
@@ -78,6 +86,10 @@ class AnacondaThread(threading.Thread):
             threadMgr.remove(self.name)
 
 def initThreading():
+    """Set up threading for anaconda's use.  This method must be called before
+       any GTK or threading code is called, or else threads will only run when
+       an event is triggered in the GTK main loop.
+    """
     from gi.repository import GObject
     GObject.threads_init()
 
diff --git a/pyanaconda/ui/gui/spokes/__init__.py b/pyanaconda/ui/gui/spokes/__init__.py
index 16e2d62be..b60fc1155 100644
--- a/pyanaconda/ui/gui/spokes/__init__.py
+++ b/pyanaconda/ui/gui/spokes/__init__.py
@@ -93,9 +93,10 @@ class Spoke(UIObject):
 
     @property
     def completed(self):
-        """Has this spoke been visited and completed?  If not, a special
-           warning icon will be shown on the Hub and installation will not be
-           allowed to proceed.
+        """Has this spoke been visited and completed?  If not, a special warning
+           icon will be shown on the Hub beside the spoke, and a highlighted
+           message will be shown at the bottom of the Hub.  Installation will not
+           be allowed to proceed until all spokes are complete.
         """
         return False
 
@@ -105,6 +106,16 @@ class Spoke(UIObject):
            a very brief string.  The purpose of this is to display something
            on the Hub under the Spoke's title so the user can tell at a glance
            how things are configured.
+
+           A spoke's status line on the Hub can also be overloaded to provide
+           information about why a Spoke is not yet ready, or if an error has
+           occurred when setting it up.  This can be done by calling
+           send_message from pyanaconda.ui.gui.communication with the target
+           Spoke's class name and the message to be displayed.
+
+           If the Spoke was not yet ready when send_message was called, the
+           message will be overwritten with the value of this status property
+           when the Spoke becomes ready.
         """
         raise NotImplementedError
 
@@ -206,6 +217,13 @@ class NormalSpoke(Spoke):
            displayed.  Almost all spokes should keep the default value here.
            Only override this method if the Spoke requires some potentially
            long-lived process (like storage probing) before it's ready.
+
+           A Spoke may be marked as ready or not by calling send_ready or
+           send_not_ready from pyanaconda.ui.gui.communication with the
+           target Spoke's class name.
+
+           While a Spoke is not ready, a progress message may be shown to
+           give the user some feedback.  See the status property for details.
         """
         return True