Doc-string updates

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_4_BRANCH@19782 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

wxPython/wxPython/lib/scrolledpanel.py

@@ -15,7 +15,7 @@ class wxScrolledPanel( wxScrolledWindow ):
     """
 wxScrolledPanel fills a "hole" in the implementation of wxScrolledWindow,
 providing automatic scrollbar and scrolling behavior and the tab traversal
-mangement that wxScrolledWindow lacks.  This code was based on the original
+management that wxScrolledWindow lacks.  This code was based on the original
 demo code showing how to do this, but is now available for general use
 as a proper class (and the demo is now converted to just use it.)
 """

wxPython/wxPython/tools/dbg.py

@@ -11,8 +11,8 @@
 """
 This module provides a useful debugging framework that supports
 showing nesting of function calls and allows a program to contain
-lots of dbg() print statements that can easily be turned off
+lots of debugging print statements that can easily be turned on
-once the code has been debugged.  It also supports the ability to
+or off to debug the code.  It also supports the ability to
 have each function indent the debugging statements contained
 within it, including those of any other function called within
 its scope, thus allowing you to see in what order functions are
@@ -24,11 +24,16 @@ not entirely clear, and because wxPython programs can't be run
 from inside other debugging environments that have their own
 message loops.
 
-the dbg() function this module provides takes a set of positional
+This module defines a Logger class, responsible for managing
+debugging output.  Each Logger instance can be given a name
+at construction; if this is done, '<name>:' will precede each
+logging output made by that Logger instance.
+
+The log() function this class provides takes a set of positional
 arguments that are printed in order if debugging is enabled
 (just like print does), followed by a set of keyword arguments
-that control the behavior of the dbg() function itself on subsequent
+that control the behavior of the log() function itself on subsequent
-calls:
+calls.  The current keyword arguments are:
 
 indent
     When set to a value of 1, this increments the current
@@ -43,6 +48,16 @@ enable
     When set to a value of 0, dbg output is turned off.  (dbg
     output is off by default.)
 
+suspend
+    When set to a value of 1, this increments the current
+    "suspension" level.  This makes it possible for a function
+    to temporarily suspend its and any of its dependents'
+    potential outputs that use the same Logger instance.
+    When set to a value of 0, the suspension level is
+    decremented.  When the value goes back to 0, potential
+    logging is resumed (actual output depends on the
+    "enable" status of the Logger instance in question.)
+
 wxlog
     When set to a value of 1, the output will be sent to the
     active wxLog target.
@@ -55,40 +70,45 @@ stream
     be restored (if stacked.)  If set to None without previously
     changing it will result in no action being taken.
 
+You can also call the log function implicitly on the Logger
+instance, ie. you can type:
+    from wxPython.tools.dbg import Logger
+    dbg = Logger()
+    dbg('something to print')
 
 Using this fairly simple mechanism, it is possible to get fairly
 useful debugging output in a program.  Consider the following
 code example:
 
 >>> d = {1:'a', 2:'dictionary', 3:'of', 4:'words'}
->>> logger = dbg.Logger()
+>>> dbg = dbg.Logger('module')
->>> dbg = logger.dbg
 >>> dbg(enable=1)
+module: dbg enabled
 >>> def foo(d):
-        dbg('foo', indent=1)
+...     dbg('foo', indent=1)
->>>     bar(d)
+...     bar(d)
->>>     dbg('end of foo', indent=0)
+...     dbg('end of foo', indent=0)
->>>
+...
 >>> def bar(d):
->>>     dbg('bar', indent=1)
+...     dbg('bar', indent=1)
->>>     dbg('contents of d:', indent=1)
+...     dbg('contents of d:', indent=1)
->>>     l = d.items()
+...     l = d.items()
->>>     l.sort()
+...     l.sort()
->>>     for key, value in l:
+...     for key, value in l:
->>>         dbg('%d =' % key, value)
+...         dbg('%d =' % key, value)
->>>     dbg(indent=0)
+...     dbg(indent=0)
->>>     dbg('end of bar', indent=0)
+...     dbg('end of bar', indent=0)
->>>
+...
 >>> foo(d)
-foo
+module: foo
-   bar
+   module: bar
-      contents of d:
+      module: contents of d:
-         1 = a
+         module: 1 = a
-         2 = dictionary
+         module: 2 = dictionary
-         3 = of
+         module: 3 = of
-         4 = words
+         module: 4 = words
-      end of bar
+      module: end of bar
-   end of foo
+   module: end of foo
 >>>
 
 """