Improved hscommon.gui docs

hscommon/gui/text_field.py

@@ -8,7 +8,44 @@
 from .base import GUIObject
 from ..util import nonone
 
+class TextFieldView:
+    """Expected interface for :class:`TextField`'s view.
+    
+    *Not actually used in the code. For documentation purposes only.*
+    
+    Our view is expected to sync with :attr:`TextField.text` "both ways", that is, update the
+    model's text when the user types something, but also update the text field when :meth:`refresh`
+    is called.
+    """
+    def refresh(self):
+        """Refreshes the contents of the input widget.
+        
+        Ensures that the contents of the input widget is actually :attr:`TextField.text`.
+        """
+
 class TextField(GUIObject):
+    """Cross-toolkit text field.
+    
+    Represents a UI element allowing the user to input a text value. Its main attribute is
+    :attr:`text` which acts as the store of the said value.
+    
+    When our model value isn't a string, we have a built-in parsing/formatting mechanism allowing
+    us to directly retrieve/set our non-string value through :attr:`value`.
+    
+    Subclasses :class:`hscommon.gui.base.GUIObject`. Expected view: :class:`TextFieldView`.
+    
+    .. attribute:: text
+        
+        *str*. The text that is currently displayed in the widget. This property can be set. When it
+        is, :meth:`refresh` is called and the view is synced with our value. Always in sync with
+        :attr:`value`.
+    
+    .. attribute:: value
+        
+        The "parsed" representation of :attr:`text`. By default, it's a mirror of :attr:`text`, but
+        a subclass can override :meth:`_parse` and :meth:`_format` to have anything else. Always in
+        sync with :attr:`text`.
+    """
     def __init__(self):
         GUIObject.__init__(self)
         self._text = ''
@@ -16,13 +53,25 @@ class TextField(GUIObject):
     
     #--- Virtual
     def _parse(self, text):
+        """(Virtual) Parses ``text`` to put into :attr:`value`.
+        
+        Returns the parsed version of ``text``. Called whenever :attr:`text` changes.
+        """
         return text
     
     def _format(self, value):
+        """(Virtual) Formats ``value`` to put into :attr:`text`.
+        
+        Returns the formatted version of ``value``. Called whenever :attr:`value` changes.
+        """
         return value
     
     def _update(self, newvalue):
-        pass
+        """(Virtual) Called whenever we have a new value.
+        
+        Whenever our text/value store changes to a new value (different from the old one), this
+        method is called. By default, it does nothing but you can override it if you want.
+        """
     
     #--- Override
     def _view_updated(self):
@@ -30,6 +79,8 @@ class TextField(GUIObject):
     
     #--- Public
     def refresh(self):
+        """Triggers a view :meth:`~TextFieldView.refresh`.
+        """
         self.view.refresh()
     
     @property