Added more documentation for MagicHelper.

IPython/qt/console/magic_helper.py

@@ -1,4 +1,4 b''
-"""Magic Helper - dockable widget showing magic commands for the MainWindow
+"""MagicHelper - dockable widget showing magic commands for the MainWindow
 
 
 Authors:
@@ -22,28 +22,50 b' from IPython.external.qt import QtGui,QtCore'
 from IPython.core.magic import magic_escapes
 
 class MagicHelper(QtGui.QDockWidget):
+    """MagicHelper - dockable widget for convenient search and running of
+                     magic command for IPython QtConsole.
+    """
+
+    #---------------------------------------------------------------------------
+    # signals
+    #---------------------------------------------------------------------------
 
     pasteRequested = QtCore.pyqtSignal(str, name = 'pasteRequested')
+    """This signal is emitted when user wants to paste selected magic 
+       command into the command line.
+    """
+
     runRequested = QtCore.pyqtSignal(str, name = 'runRequested')
+    """This signal is emitted when user wants to execute selected magic command
+    """
+
     readyForUpdate = QtCore.pyqtSignal(name = 'readyForUpdate')
+    """This signal is emitted when MagicHelper is ready to be populated.
+       Since kernel querying mechanisms are out of scope of this class,
+       it expects its owner to invoke MagicHelper.populate_magic_helper()
+       as a reaction on this event.
+    """
 
     #---------------------------------------------------------------------------
-    # 'object' interface
+    # constructor
     #---------------------------------------------------------------------------
 
     def __init__(self, name, parent):
-
         super(MagicHelper, self).__init__(name, parent)
 
         self.data = None
 
         class MinListWidget(QtGui.QListWidget):
+            """Temp class to overide the default QListWidget size hint
+               in order to make MagicHelper narrow
+            """
             def sizeHint(self):
                 s = QtCore.QSize()
                 s.setHeight(super(MinListWidget,self).sizeHint().height())
                 s.setWidth(self.sizeHintForColumn(0))
                 return s
 
+        # construct content
         self.frame = QtGui.QFrame()
         self.search_label = QtGui.QLabel("Search:")
         self.search_line = QtGui.QLineEdit()
@@ -52,6 +74,7 b' class MagicHelper(QtGui.QDockWidget):'
         self.paste_button = QtGui.QPushButton("Paste")
         self.run_button = QtGui.QPushButton("Run")
         
+        # layout all the widgets
         main_layout = QtGui.QVBoxLayout()
         search_layout = QtGui.QHBoxLayout()
         search_layout.addWidget(self.search_label)
@@ -67,7 +90,8 b' class MagicHelper(QtGui.QDockWidget):'
         self.frame.setLayout(main_layout)
         self.setWidget(self.frame)
 
-        self.visibilityChanged[bool].connect( self.update_magic_helper )
+        # connect all the relevant signals to handlers
+        self.visibilityChanged[bool].connect( self._update_magic_helper )
         self.search_class.activated[int].connect( 
             self.class_selected
         )
@@ -84,15 +108,29 b' class MagicHelper(QtGui.QDockWidget):'
             self.run_requested
         )
 
-    def update_magic_helper(self, visible):
+    #---------------------------------------------------------------------------
+    # implementation
+    #---------------------------------------------------------------------------
+
+    def _update_magic_helper(self, visible):
+        """Start update sequence. 
+           This method is called when MagicHelper becomes visible. It clears
+           the content and emits readyForUpdate signal. The owner of the 
+           instance is expected to invoke populate_magic_helper() when magic
+           info is available.
+        """
         if not visible or self.data != None:
             return
         self.data = {}
         self.search_class.clear()
         self.search_class.addItem("Populating...")
+        self.search_list.clear()
         self.readyForUpdate.emit()
 
     def populate_magic_helper(self, data):
+        """Expects data returned by lsmagics query from kernel.
+           Populates the search_class and search_list with relevant items.
+        """
         self.search_class.clear()
         self.search_list.clear()
                 
@@ -115,17 +153,24 b' class MagicHelper(QtGui.QDockWidget):'
         self.filter_magic_helper('.', 'any')
 
     def class_selected(self, index):
+        """Handle search_class selection changes
+        """
         item = self.search_class.itemData(index)
         regex = self.search_line.text()
         self.filter_magic_helper(regex = regex, cls = item)
 
     def search_changed(self, search_string):
+        """Handle search_line text changes.
+           The text is interpreted as a regular expression
+        """
         item = self.search_class.itemData(
             self.search_class.currentIndex()
         )
         self.filter_magic_helper(regex = search_string, cls = item)
 
     def _get_current_search_item(self, item = None):
+        """Retrieve magic command currently selected in the search_list
+        """
         text = None
         if not isinstance(item, QtGui.QListWidgetItem):
             item = self.search_list.currentItem()        
@@ -133,16 +178,24 b' class MagicHelper(QtGui.QDockWidget):'
         return text
 
     def paste_requested(self, item = None):
+        """Emit pasteRequested signal with currently selected item text
+        """
         text = self._get_current_search_item(item)
         if text != None:
             self.pasteRequested.emit(text)
 
     def run_requested(self, item = None):
+        """Emit runRequested signal with currently selected item text
+        """
         text = self._get_current_search_item(item)
         if text != None:            
             self.runRequested.emit(text)
 
     def filter_magic_helper(self, regex, cls):
+        """Update search_list with magic commands whose text match
+           regex and class match cls.
+           If cls equals 'any' - any class matches.
+        """
         if regex == "" or regex == None:
             regex = '.'
         if cls == None: