Added some doc strings on the widgets.

Also address the comments Matthias left me.

IPython/html/widgets/__init__.py

@@ -14,11 +14,10 b' from .interaction import interact, interactive, fixed'
 # Deprecated classes
 from .widget_bool import CheckboxWidget, ToggleButtonWidget
 from .widget_button import ButtonWidget
-from .widget_container import ContainerWidget, HBox, VBox, PopupWidget
+from .widget_container import ContainerWidget, PopupWidget
 from .widget_float import FloatTextWidget, BoundedFloatTextWidget, FloatSliderWidget, FloatProgressWidget
 from .widget_image import ImageWidget
 from .widget_int import IntTextWidget, BoundedIntTextWidget, IntSliderWidget, IntProgressWidget
 from .widget_selection import RadioButtonsWidget, ToggleButtonsWidget, DropdownWidget, SelectWidget
 from .widget_selectioncontainer import TabWidget, AccordionWidget
 from .widget_string import HTMLWidget, LatexWidget, TextWidget, TextareaWidget
-from .interaction import interact, interactive, fixed

IPython/html/widgets/widget_bool.py

@@ -21,17 +21,23 b' from IPython.utils.warn import DeprecatedClass'
 # Classes
 #-----------------------------------------------------------------------------
 class _Bool(DOMWidget):
+    """A base class for creating widgets that represent booleans."""
     value = Bool(False, help="Bool value", sync=True)
-    description = Unicode('', help="Description of the boolean (label).", sync=True) 
+    description = Unicode('', help="Description of the boolean (label).", sync=True)
     disabled = Bool(False, help="Enable or disable user changes.", sync=True)
 
 
 class Checkbox(_Bool):
+    """Displays a boolean `value`."""
     _view_name = Unicode('CheckboxView', sync=True)
 
 
 class ToggleButton(_Bool):
-    _view_name = Unicode('ToggleButtonView', sync=True)
+    """Displays a boolean `value`."""
     
+    _view_name = Unicode('ToggleButtonView', sync=True)
+
+
+# Remove in IPython 4.0
 CheckboxWidget = DeprecatedClass(Checkbox, 'CheckboxWidget')
 ToggleButtonWidget = DeprecatedClass(ToggleButton, 'ToggleButtonWidget')

IPython/html/widgets/widget_button.py

@@ -22,6 +22,10 b' from IPython.utils.warn import DeprecatedClass'
 # Classes
 #-----------------------------------------------------------------------------
 class Button(DOMWidget):
+    """Button widget.
+
+    This widget has an `on_click` method that allows you to listen for the 
+    user clicking on the button.  The click event itself is stateless."""
     _view_name = Unicode('ButtonView', sync=True)
 
     # Keys
@@ -56,5 +60,6 b' class Button(DOMWidget):'
         if content.get('event', '') == 'click':
             self._click_handlers(self)
 
-    
+
+# Remove in IPython 4.0
 ButtonWidget = DeprecatedClass(Button, 'ButtonWidget')

IPython/html/widgets/widget_container.py

@@ -11,6 +11,7 b' from IPython.utils.traitlets import Unicode, Tuple, TraitError, Int, CaselessStr'
 from IPython.utils.warn import DeprecatedClass
 
 class Container(DOMWidget):
+    """Displays multiple widgets in a group."""
     _view_name = Unicode('ContainerView', sync=True)
 
     # Child widgets in the container.
@@ -29,6 +30,7 b' class Container(DOMWidget):'
 
 
 class Popup(Container):
+    """Displays multiple widgets in an in page popup div."""
     _view_name = Unicode('PopupView', sync=True)
     
     description = Unicode(sync=True)
@@ -36,6 +38,7 b' class Popup(Container):'
 
 
 class FlexContainer(Container):
+    """Displays multiple widgets using the flexible box model."""
     _view_name = Unicode('FlexContainerView', sync=True)
     orientation = CaselessStrEnum(values=['vertical', 'horizontal'], default_value='vertical', sync=True)
     flex = Int(0, sync=True, help="""Specify the flexible-ness of the model.""")
@@ -54,14 +57,17 b' class FlexContainer(Container):'
 
 
 def VBox(*pargs, **kwargs):
+    """Displays multiple widgets vertically using the flexible box model."""
     kwargs['orientation'] = 'vertical'
     return FlexContainer(*pargs, **kwargs)
 
 def HBox(*pargs, **kwargs):
+    """Displays multiple widgets horizontally using the flexible box model."""
     kwargs['orientation'] = 'horizontal'
     return FlexContainer(*pargs, **kwargs)
 
 
+# Remove in IPython 4.0
 ContainerWidget = DeprecatedClass(Container, 'ContainerWidget')
 PopupWidget = DeprecatedClass(Popup, 'PopupWidget')
 

IPython/html/widgets/widget_float.py

@@ -61,8 +61,8 b' class FloatSlider(_BoundedFloat):'
 class FloatProgress(_BoundedFloat):
     _view_name = Unicode('ProgressView', sync=True)
 
-_FloatWidget = DeprecatedClass(_Float, '_FloatWidget')
-_BoundedFloatWidget = DeprecatedClass(_BoundedFloat, '_BoundedFloatWidget')
+
+# Remove in IPython 4.0
 FloatTextWidget = DeprecatedClass(FloatText, 'FloatTextWidget')
 BoundedFloatTextWidget = DeprecatedClass(BoundedFloatText, 'BoundedFloatTextWidget')
 FloatSliderWidget = DeprecatedClass(FloatSlider, 'FloatSliderWidget')

IPython/html/widgets/widget_image.py

@@ -23,6 +23,12 b' from IPython.utils.warn import DeprecatedClass'
 # Classes
 #-----------------------------------------------------------------------------
 class Image(DOMWidget):
+    """Displays an image as a widget.
+
+    The `value` of this widget accepts a byte string.  The byte string is the raw
+    image data that you want the browser to display.  You can explicitly define
+    the format of the byte string using the `format` trait (which defaults to
+    "png")."""
     _view_name = Unicode('ImageView', sync=True)
     
     # Define the custom state properties to sync with the front-end
@@ -35,4 +41,6 b' class Image(DOMWidget):'
     def _value_changed(self, name, old, new):
         self._b64value = base64.b64encode(new)
 
+
+# Remove in IPython 4.0
 ImageWidget = DeprecatedClass(Image, 'ImageWidget')

IPython/html/widgets/widget_int.py

@@ -21,12 +21,15 b' from IPython.utils.warn import DeprecatedClass'
 # Classes
 #-----------------------------------------------------------------------------
 class _Int(DOMWidget):
+    """Base class used to create widgets that represent an int."""
     value = CInt(0, help="Int value", sync=True) 
     disabled = Bool(False, help="Enable or disable user changes", sync=True)
     description = Unicode(help="Description of the value this widget represents", sync=True)
 
 
 class _BoundedInt(_Int):
+    """Base class used to create widgets that represent a int that is bounded
+    by a minium and maximum."""
     step = CInt(1, help="Minimum step that the value can take (ignored by some views)", sync=True)
     max = CInt(100, help="Max value", sync=True)
     min = CInt(0, help="Min value", sync=True)
@@ -43,14 +46,17 b' class _BoundedInt(_Int):'
 
 
 class IntText(_Int):
+    """Textbox widget that represents a int."""
     _view_name = Unicode('IntTextView', sync=True)
 
 
 class BoundedIntText(_BoundedInt):
+    """Textbox widget that represents a int bounded by a minimum and maximum value."""
     _view_name = Unicode('IntTextView', sync=True)
 
 
 class IntSlider(_BoundedInt):
+    """Slider widget that represents a int bounded by a minimum and maximum value."""
     _view_name = Unicode('IntSliderView', sync=True)
     orientation = Enum([u'horizontal', u'vertical'], u'horizontal', 
         help="Vertical or horizontal.", sync=True)
@@ -58,10 +64,11 b' class IntSlider(_BoundedInt):'
 
 
 class IntProgress(_BoundedInt):
+    """Progress bar that represents a int bounded by a minimum and maximum value."""
     _view_name = Unicode('ProgressView', sync=True)
 
-_IntWidget = DeprecatedClass(_Int, '_IntWidget')
-_BoundedIntWidget = DeprecatedClass(_BoundedInt, '_BoundedIntWidget')
+
+# Remove in IPython 4.0
 IntTextWidget = DeprecatedClass(IntText, 'IntTextWidget')
 BoundedIntTextWidget = DeprecatedClass(BoundedIntText, 'BoundedIntTextWidget')
 IntSliderWidget = DeprecatedClass(IntSlider, 'IntSliderWidget')

IPython/html/widgets/widget_selection.py

@@ -111,21 +111,28 b' class _Selection(DOMWidget):'
 
 
 class ToggleButtons(_Selection):
+    """Group of toggle buttons that represent an enumeration.  Only one toggle
+    button can be toggled at any point in time.""" 
     _view_name = Unicode('ToggleButtonsView', sync=True)
 
 
 class Dropdown(_Selection):
+    """Allows you to select a single item from a dropdown."""
     _view_name = Unicode('DropdownView', sync=True)
 
 
 class RadioButtons(_Selection):
+    """Group of radio buttons that represent an enumeration.  Only one radio
+    button can be toggled at any point in time.""" 
     _view_name = Unicode('RadioButtonsView', sync=True)
     
 
 class Select(_Selection):
+    """Listbox that only allows one item to be selected at any given time."""
     _view_name = Unicode('SelectView', sync=True)
 
-_SelectionWidget = DeprecatedClass(_Selection, '_SelectionWidget')
+
+# Remove in IPython 4.0
 ToggleButtonsWidget = DeprecatedClass(ToggleButtons, 'ToggleButtonsWidget')
 DropdownWidget = DeprecatedClass(Dropdown, 'DropdownWidget')
 RadioButtonsWidget = DeprecatedClass(RadioButtons, 'RadioButtonsWidget')

IPython/html/widgets/widget_selectioncontainer.py

@@ -22,6 +22,7 b' from IPython.utils.warn import DeprecatedClass'
 # Classes
 #-----------------------------------------------------------------------------
 class _SelectionContainer(ContainerWidget):
+    """Base class used to display multiple child widgets."""
     _titles = Dict(help="Titles of the pages", sync=True)
     selected_index = CInt(0, sync=True)
 
@@ -52,12 +53,15 b' class _SelectionContainer(ContainerWidget):'
 
 
 class Accordion(_SelectionContainer):
+    """Displays children each on a separate accordion page."""
     _view_name = Unicode('AccordionView', sync=True)
 
 
 class Tab(_SelectionContainer):
+    """Displays children each on a separate accordion tab."""
     _view_name = Unicode('TabView', sync=True)
 
-_SelectionContainerWidget = DeprecatedClass(_SelectionContainer, '_SelectionContainerWidget')
+
+# Remove in IPython 4.0
 AccordionWidget = DeprecatedClass(Accordion, 'AccordionWidget')
 TabWidget = DeprecatedClass(Tab, 'TabWidget')

IPython/html/widgets/widget_string.py

@@ -21,6 +21,7 b' from IPython.utils.warn import DeprecatedClass'
 # Classes
 #-----------------------------------------------------------------------------
 class _String(DOMWidget):
+    """Base class used to create widgets that represent a string."""
     value = Unicode(help="String value", sync=True)
     disabled = Bool(False, help="Enable or disable user changes", sync=True)
     description = Unicode(help="Description of the value this widget represents", sync=True)
@@ -28,14 +29,18 b' class _String(DOMWidget):'
 
 
 class HTML(_String):
+    """Renders the string `value` as HTML."""
     _view_name = Unicode('HTMLView', sync=True)
 
 
 class Latex(_String):
+    """Renders math inside the string `value` as Latex (requires $ $ or $$ $$ 
+    and similar latex tags)."""
     _view_name = Unicode('LatexView', sync=True)
 
 
 class Textarea(_String):
+    """Multiline text area widget."""
     _view_name = Unicode('TextareaView', sync=True)
 
     def scroll_to_bottom(self):
@@ -43,6 +48,7 b' class Textarea(_String):'
 
 
 class Text(_String):
+    """Single line textbox widget."""
     _view_name = Unicode('TextView', sync=True)
 
     def __init__(self, **kwargs):
@@ -73,7 +79,8 b' class Text(_String):'
             Whether to unregister the callback"""
         self._submission_callbacks.register_callback(callback, remove=remove)
 
-_StringWidget = DeprecatedClass(_String, '_StringWidget')
+
+# Remove in IPython 4.0
 HTMLWidget = DeprecatedClass(HTML, 'HTMLWidget')
 LatexWidget = DeprecatedClass(Latex, 'LatexWidget')
 TextareaWidget = DeprecatedClass(Textarea, 'TextareaWidget')