[Python-checkins] cpython (2.7): Issue #14117: Inprove help text and docstrings, some for clarity, some just to

Wed Jun 25 04:22:18 CEST 2014

http://hg.python.org/cpython/rev/129ec3d90a67
changeset: 91381:129ec3d90a67
branch: 2.7
user: Terry Jan Reedy <tjreedy at udel.edu>
date: Tue Jun 24 22:21:36 2014 -0400
summary:
 Issue #14117: Inprove help text and docstrings, some for clarity, some just to
fit in the default width of the text window (45 chars).
files:
 Demo/turtle/demohelp.txt | 40 ++++++++-------
 Demo/turtle/tdemo_paint.py | 12 +++-
 Demo/turtle/tdemo_peace.py | 16 ++----
 Demo/turtle/tdemo_planet_and_moon.py | 9 +--
 Demo/turtle/tdemo_tree.py | 6 +-
 5 files changed, 42 insertions(+), 41 deletions(-)

diff --git a/Demo/turtle/demohelp.txt b/Demo/turtle/demohelp.txt
--- a/Demo/turtle/demohelp.txt
+++ b/Demo/turtle/demohelp.txt
@@ -2,7 +2,7 @@
 
 ----------------------------------------------
 
- xturtleDemo - Help
+ turtleDemo - Help
 
 ----------------------------------------------
 
@@ -53,27 +53,29 @@
 
 (2) How to add your own demos to the demo repository
 
- - scriptname: must begin with tdemo_ ,
+ - The script name must begin with tdemo_ ,
 so it must have the form tdemo_<your-script-name>.py
 
- - place: same directory as xturtleDemo.py or some
- subdirectory, the name of which must also begin with
- tdemo_.....
+ - The code must contain a main() function which will
+ be executed by the viewer (see provided example scripts).
+ It may return a string which will be displayed in the Label below
+ the source code window (when execution has finished.)
+	 
+ - In order to run mydemo.py by itself, such as during development,
+ add the following at the end of the file:
 
- - requirements on source code:
- code must contain a main() function which will
- be executed by the viewer (see provided example scripts)
- main() may return a string which will be displayed
- in the Label below the source code window (when execution
- has finished.)
+ if __name__ == '__main__':
+ main()
+ mainloop() # keep window 
 
- If the demo is EVENT DRIVEN, main must return the string
- "EVENTLOOP". This informs the demo viewer that the script is
- still running and must be stopped by the user!
+ python -m turtledemo.mydemo # will then run it
 
- If an "EVENTLOOP" demo runs by itself, as with clock, which uses
- ontimer, or minimal_hanoi, which loops by recursion, then the
- code should catch the turtle.Terminator exception that will be
- raised when the user presses the STOP button. (Paint is not such
- a demo; it only acts in response to mouse clicks and movements.)
+ - If the demo is EVENT DRIVEN, main must return the string
+ "EVENTLOOP". This informs the demo viewer that the script is
+ still running and must be stopped by the user!
 
+ If an "EVENTLOOP" demo runs by itself, as with clock, which uses
+ ontimer, or minimal_hanoi, which loops by recursion, then the
+ code should catch the turtle.Terminator exception that will be
+ raised when the user presses the STOP button. (Paint is not such
+ a demo; it only acts in response to mouse clicks and movements.)
diff --git a/Demo/turtle/tdemo_paint.py b/Demo/turtle/tdemo_paint.py
--- a/Demo/turtle/tdemo_paint.py
+++ b/Demo/turtle/tdemo_paint.py
@@ -3,11 +3,15 @@
 
 tdemo_paint.py
 
-A simple eventdriven paint program
+A simple event-driven paint program
 
-- use left mouse button to move turtle
-- middle mouse button to change color
-- right mouse button do turn filling on/off
+- left mouse button moves turtle
+- middle mouse button changes color
+- right mouse button toogles betweem pen up
+(no line drawn when the turtle moves) and
+pen down (line is drawn). If pen up follows
+at least two pen-down moves, the polygon that
+includes the starting point is filled.
 -------------------------------------------
 Play around by clicking into the canvas
 using all three mouse buttons.
diff --git a/Demo/turtle/tdemo_peace.py b/Demo/turtle/tdemo_peace.py
--- a/Demo/turtle/tdemo_peace.py
+++ b/Demo/turtle/tdemo_peace.py
@@ -3,14 +3,10 @@
 
 tdemo_peace.py
 
-A very simple drawing suitable as a beginner's
-programming example.
-
-Uses only commands, which are also available in
-old turtle.py.
-
-Intentionally no variables are used except for the
-colorloop:
+A simple drawing suitable as a beginner's
+programming example. Aside from the
+peacecolors assignment and the for loop,
+it only uses turtle commands.
 """
 
 from turtle import *
@@ -21,7 +17,7 @@
 "royalblue1", "dodgerblue4")
 
 reset()
- s = Screen()
+ Screen()
 up()
 goto(-320,-195)
 width(70)
@@ -58,7 +54,7 @@
 up()
 
 goto(0,300) # vanish if hideturtle() is not available ;-)
- return "Done!!"
+ return "Done!"
 
 if __name__ == "__main__":
 main()
diff --git a/Demo/turtle/tdemo_planet_and_moon.py b/Demo/turtle/tdemo_planet_and_moon.py
--- a/Demo/turtle/tdemo_planet_and_moon.py
+++ b/Demo/turtle/tdemo_planet_and_moon.py
@@ -12,9 +12,9 @@
 Planet has a circular orbit, moon a stable
 orbit around the planet.
 
-You can hold the movement temporarily by pressing
-the left mouse button with mouse over the
-scrollbar of the canvas.
+You can hold the movement temporarily by
+pressing the left mouse button with the
+mouse over the scrollbar of the canvas.
 
 """
 from turtle import Shape, Turtle, mainloop, Vec2D as Vec
@@ -108,6 +108,5 @@
 return "Done!"
 
 if __name__ == '__main__':
- msg = main()
- print msg
+ main()
 mainloop()
diff --git a/Demo/turtle/tdemo_tree.py b/Demo/turtle/tdemo_tree.py
--- a/Demo/turtle/tdemo_tree.py
+++ b/Demo/turtle/tdemo_tree.py
@@ -11,9 +11,9 @@
 (1) a tree-generator, where the drawing is
 quasi the side-effect, whereas the generator
 always yields None.
-(2) Turtle-cloning: At each branching point the
-current pen is cloned. So in the end there
-are 1024 turtles.
+(2) Turtle-cloning: At each branching point
+the current pen is cloned. So in the end
+there are 1024 turtles.
 """
 from turtle import Turtle, mainloop
 from time import clock
-- 
Repository URL: http://hg.python.org/cpython
