add documentation and comments to TUI classes

4 files changed, 136 insertions, 36 deletions

diff --git a/pyanaconda/ui/tui/__init__.py b/pyanaconda/ui/tui/__init__.py
index 22acf1ca2..5f45c578e 100644
--- a/pyanaconda/ui/tui/__init__.py
+++ b/pyanaconda/ui/tui/__init__.py
@@ -1,11 +1,23 @@
 from pyanaconda import ui
 from pyanaconda.ui import common
 import simpleline as tui
+from hubs.summary import SummaryHub
+from spokes import StandaloneSpoke
 
 class ErrorDialog(tui.UIScreen):
+    """Dialog screen for reporting errors to user."""
+
     title = u"Error"
 
     def __init__(self, app, message):
+        """
+        :param app: the running application reference
+        :type app: instance of App class
+
+        :param message: the message to show to the user
+        :type message: unicode
+        """
+
         tui.UIScreen.__init__(self, app)
         self._message = message
 
@@ -18,12 +30,23 @@ class ErrorDialog(tui.UIScreen):
         return u"Press enter to exit."
 
     def input(self, key):
+        """This dialog is closed by any input."""
         self.close()
 
 class YesNoDialog(tui.UIScreen):
+    """Dialog screen for Yes - No questions."""
+
     title = u"Question"
 
     def __init__(self, app, message):
+        """
+        :param app: the running application reference
+        :type app: instance of App class
+
+        :param message: the message to show to the user
+        :type message: unicode
+        """
+
         tui.UIScreen.__init__(self, app)
         self._message = message
         self._response = None
@@ -54,11 +77,27 @@ class YesNoDialog(tui.UIScreen):
 
     @property
     def answer(self):
+        """The response can be True (yes), False (no) or None (no response)."""
         return self._response
 
 class TextUserInterface(ui.UserInterface):
+    """This is the main class for Text user interface."""
 
     def __init__(self, storage, payload, instclass):
+        """
+        For detailed description of the arguments see
+        the parent class.
+
+        :param storage: storage backend reference
+        :type storage: instance of pyanaconda.Storage
+
+        :param payload: payload (usually yum) reference
+        :type payload: instance of payload handler
+
+        :param instclass: install class reference
+        :type instclass: instance of install class
+        """
+
         ui.UserInterface.__init__(self, storage, payload, instclass)
         self._app = None
 
@@ -67,14 +106,8 @@ class TextUserInterface(ui.UserInterface):
            This method must be provided by all subclasses.
         """
         self._app = tui.App(u"Anaconda", yes_or_no_question = YesNoDialog)
-
-        from hubs.summary import SummaryHub
-        #from hubs.progress import ProgressHub
         self._hubs = [SummaryHub]
 
-
-        from spokes import StandaloneSpoke
-
         # First, grab a list of all the standalone spokes.
         path = os.path.join(os.path.dirname(__file__), "spokes")
         actionClasses = self.getActionClasses("pyanaconda.ui.tui.spokes.%s", path, self._hubs, StandaloneSpoke)
@@ -126,29 +159,3 @@ class TextUserInterface(ui.UserInterface):
         question_window = YesNoDialog(self._app, message)
         self._app.switch_window_modal(question_window)
         return question_window.answer
-
-class TUIObject(tui.UIScreen, common.UIObject):
-    title = u"Default title"
-
-    def __init__(self, app, data):
-        tui.UIScreen.__init__(self, app)
-        common.UIObject.__init__(self, data)
-
-    @property
-    def showable(self):
-        return True
-
-    def teardown(self):
-        pass
-
-    def initialize(self):
-        pass
-
-    def refresh(self, args = None):
-        """Put everything to display into self.window list."""
-        tui.UIScreen.refresh(self, args)
-
-    def retranslate(self):
-        # do retranslation stuff
-        # redraw
-        self.app.switch_screen(self)
diff --git a/pyanaconda/ui/tui/hubs/__init__.py b/pyanaconda/ui/tui/hubs/__init__.py
index 33a122e41..9d4937adb 100644
--- a/pyanaconda/ui/tui/hubs/__init__.py
+++ b/pyanaconda/ui/tui/hubs/__init__.py
@@ -1,21 +1,37 @@
 from .. import simpleline as tui
-from pyanaconda.ui.tui import TUIObject
+from pyanaconda.ui.tui.tuiobject import TUIObject
 from pyanaconda.ui.tui.spokes import collect_spokes
 from pyanaconda.ui import common
 
 class TUIHub(TUIObject, common.Hub):
+    """Base Hub class implementing the pyanaconda.ui.common.Hub interface.
+    It uses text based categories to look for relevant Spokes and manages
+    all the spokes it finds to have the proper category.
+
+    :param categories: list all the spoke categories to be displayed in this Hub
+    :type categories: list of strings
+
+    :param title: title for this Hub
+    :type title: unicode
+
+    """
+
     categories = []
     title = "Default HUB title"
 
     def __init__(self, app, data, storage, payload, instclass):
         TUIObject.__init__(self, app, data)
         common.Hub.__init__(self, data, storage, payload, instclass)
-        self._spokes = {}
-        self._keys = {}
+
+        self._spokes = {}     # holds spokes referenced by their class name
+        self._keys = {}       # holds spokes referenced by their user input key
         self._spoke_count = 0
 
+        # look for spokes having category present in self.categories
         for c in self.categories:
             spokes = collect_spokes(c)
+
+            # sort them according to their priority
             for s in sorted(spokes, key = lambda s: s.priority):
                 spoke = s(app, data, storage, payload, instclass)
                 spoke.initialize()
@@ -31,12 +47,15 @@ class TUIHub(TUIObject, common.Hub):
 
 
     def refresh(self, args = None):
+        """This methods fills the self._window list by all the objects
+        we want shown on this screen. Title and Spokes mostly."""
         TUIObject.refresh(self, args)
 
         def _prep(i, w):
             number = tui.TextWidget("%2d)" % i)
             return tui.ColumnWidget([(3, [number]), (None, [w])], 1)
 
+        # split spokes to two columns
         left = [_prep(i, w) for i,w in self._keys.iteritems() if i % 2 == 1]
         right = [_prep(i, w) for i,w in self._keys.iteritems() if i % 2 == 0]
 
@@ -46,6 +65,8 @@ class TUIHub(TUIObject, common.Hub):
         return True
 
     def input(self, key):
+        """Handle user input. Numbers are used to show a spoke, the rest is passed
+        to the higher level for processing."""
         try:
             number = int(key)
             self.app.switch_screen_with_return(self._keys[number])
diff --git a/pyanaconda/ui/tui/spokes/__init__.py b/pyanaconda/ui/tui/spokes/__init__.py
index 153b79c71..07fc3d135 100644
--- a/pyanaconda/ui/tui/spokes/__init__.py
+++ b/pyanaconda/ui/tui/spokes/__init__.py
@@ -1,5 +1,5 @@
 from .. import simpleline as tui
-from pyanaconda.ui.tui import TUIObject
+from pyanaconda.ui.tui.tuiobject import TUIObject
 from pyanaconda.ui.common import Spoke, StandaloneSpoke, NormalSpoke, PersonalizationSpoke, collect
 import os
 
@@ -7,6 +7,17 @@ __all__ = ["TUISpoke", "StandaloneSpoke", "NormalSpoke", "PersonalizationSpoke",
            "collect_spokes", "collect_categories"]
 
 class TUISpoke(TUIObject, tui.Widget, Spoke):
+    """Base TUI Spoke class implementing the pyanaconda.ui.common.Spoke API.
+    It also acts as a Widget so we can easily add it to Hub, where is shows
+    as a summary box with title, description and completed checkbox.
+
+    :param title: title of this spoke
+    :type title: unicode
+
+    :param category: category this spoke belongs to
+    :type category: string
+    """
+
     title = u"Default spoke title"
     category = u""
 
@@ -28,9 +39,11 @@ class TUISpoke(TUIObject, tui.Widget, Spoke):
         return True
 
     def input(self, key):
+        """Handle the input, the base class just forwards it to the App level."""
         return key
 
     def render(self, width):
+        """Render the summary representation for Hub to internal buffer."""
         tui.Widget.render(self, width)
         c = tui.CheckboxWidget(completed = self.completed, title = self.title, text = self.status)
         c.render(width)
diff --git a/pyanaconda/ui/tui/tuiobject.py b/pyanaconda/ui/tui/tuiobject.py
new file mode 100644
index 000000000..35c920fd3
--- /dev/null
+++ b/pyanaconda/ui/tui/tuiobject.py
@@ -0,0 +1,59 @@
+# base TUIObject for Anaconda TUI
+#
+# Copyright (C) 2012  Red Hat, Inc.
+#
+# This copyrighted material is made available to anyone wishing to use,
+# modify, copy, or redistribute it subject to the terms and conditions of
+# the GNU General Public License v.2, or (at your option) any later version.
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY expressed or implied, including the implied warranties of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.  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.  Any Red Hat trademarks that are incorporated in the
+# source code or documentation are not subject to the GNU General Public
+# License and may only be used or replicated with the express permission of
+# Red Hat, Inc.
+#
+# Red Hat Author(s): Martin Sivak <msivak@redhat.com>
+#
+
+from pyanaconda.ui import common
+import simpleline as tui
+
+class TUIObject(tui.UIScreen, common.UIObject):
+    """Base class for Anaconda specific TUI screens. Implements the
+    common pyanaconda.ui.common.UIObject interface"""
+
+    title = u"Default title"
+
+    def __init__(self, app, data):
+        tui.UIScreen.__init__(self, app)
+        common.UIObject.__init__(self, data)
+
+    @property
+    def showable(self):
+        return True
+
+    def teardown(self):
+        pass
+
+    def initialize(self):
+        """This method gets called whenever Hub or UserInterface prepares
+        all found objects for use. It is called only once and has no direct
+        connection to rendering."""
+        pass
+
+    def refresh(self, args = None):
+        """Put everything to display into self.window list."""
+        tui.UIScreen.refresh(self, args)
+
+    def retranslate(self):
+        """After language is changed, this method ensures that all the
+        texts on screen are translated. It only needs to refresh the
+        screen in text mode, as translation will happen automatically
+        and there is no way to change labels on previously displayed content."""
+
+        # redraw
+        self.app.switch_screen(self)