Add docstring to explain format string syntax.

2 files changed, 9 insertions, 1 deletions

diff --git a/NEWS b/NEWS
index 9b556c2..3f56359 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,8 @@ Version 0.14, released XXXXXXXXXX
 * A method for printing error messages is provided. They are printed to
   the standard error.
 * The `PercentDone` class handles zero total amounts better now.
+* Widgets may now be added using a simple format string. See
+  `ttystatus.TerminalStatus.format` method.
 
 Version 0.13, released 2011-08-18
 ---------------------------------
diff --git a/ttystatus/status.py b/ttystatus/status.py
index 722d69f..e8192e3 100644
--- a/ttystatus/status.py
+++ b/ttystatus/status.py
@@ -46,7 +46,13 @@ class TerminalStatus(object):
                 self._interests[key] = self._interests.get(key, []) + [widget]
 
     def format(self, format_string):
-        '''Add new widgets based on format string.'''
+        '''Add new widgets based on format string.
+        
+        The format string is taken literally, except that ``%%`` is a
+        literal percent character, and ``%Foo(a,b,c)`` is a widget
+        of type ``Foo`` with parameters a, b, and c.
+        
+        '''
         for widget in ttystatus.fmt.parse(format_string):
             self.add(widget)