Rev 3009: Docstring improvement and remove TODO's from progres.py. in http://people.ubuntu.com/~robertc/baz2.0/nested-pb

[Robert Collins]

At http://people.ubuntu.com/~robertc/baz2.0/nested-pb

------------------------------------------------------------
revno: 3009
revision-id:robertc at robertcollins.net-20071119195948-n46szsvkgl0c9lj4
parent: robertc at robertcollins.net-20071119191346-42ifg0e154gwbain
committer: Robert Collins <robertc at robertcollins.net>
branch nick: trivialities
timestamp: Tue 2007-11-20 06:59:48 +1100
message:
  Docstring improvement and remove TODO's from progres.py.
modified:
  bzrlib/progress.py             progress.py-20050610070202-df9faaab791964c0
=== modified file 'bzrlib/progress.py'
--- a/bzrlib/progress.py	2007-11-19 19:13:46 +0000
+++ b/bzrlib/progress.py	2007-11-19 19:59:48 +0000
@@ -16,22 +16,18 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
 
-"""Simple text-mode progress indicator.
-
-To display an indicator, create a ProgressBar object.  Call it,
-passing Progress objects indicating the current state.  When done,
-call clear().
-
-Progress is suppressed when output is not sent to a terminal, so as
-not to clutter log files.
+"""Progress indicators.
+
+The usual way to use this is via bzrlib.ui.ui_factory.nested_progress_bar which
+will maintain a ProgressBarStack for you.
+
+For direct use, the factory ProgressBar will return an auto-detected progress
+bar that should match your terminal type. You can manually create a
+ProgressBarStack too if you need multiple levels of cooperating progress bars.
+Note that bzrlib's internal functions use the ui module, so if you are using
+bzrlib it really is best to use bzrlib.ui.ui_factory.
 """
 
-# TODO: should be a global option e.g. --silent that disables progress
-# indicators, preferably without needing to adjust all code that
-# potentially calls them.
-
-# TODO: If not on a tty perhaps just print '......' for the benefit of IDEs, etc
-
 # TODO: Optionally show elapsed time instead/as well as ETA; nicer
 # when the rate is unpredictable