doc: revisions to clock.py

kivy/clock.py

@@ -3,7 +3,7 @@ Clock object
 ============
 
 The :class:`Clock` object allows you to schedule a function call in the
-future; once or on interval::
+future; once or repeatedly at specified intervals::
 
     def my_callback(dt):
         pass
@@ -22,7 +22,7 @@ future; once or on interval::
     If the callback returns False, the schedule will be removed.
 
 If you want to schedule a function to call with default arguments, you can use
-`functools.partial
+the `functools.partial
 <http://docs.python.org/library/functools.html#functools.partial>`_ python
 module::
 
@@ -34,7 +34,7 @@ module::
     Clock.schedule_interval(partial(my_callback, 'my value', 'my key'), 0.5)
 
 Conversely, if you want to schedule a function that doesn't accept the dt
-argument, you can use `lambda
+argument, you can use a `lambda
 <http://docs.python.org/2/reference/expressions.html#lambda>`_ expression
 to write a short function that does accept dt. For Example::
 
@@ -47,13 +47,13 @@ to write a short function that does accept dt.  For Example::
 
     You cannot unschedule an anonymous function unless you keep a reference to
     it.  It's better to add \*args to your function definition so that it can be
-    called with or without the clock.
+    called with an arbitrary number of parameters.
 
 .. important::
 
-    The callback is weak-referenced: you are responsible to keep a reference to
-    your original object/callback. If you don't keep a reference, the Clock will
-    never execute your callback. For example::
+    The callback is weak-referenced: you are responsible for keeping a reference
+    to your original object/callback. If you don't keep a reference, the ClockBase
+    will never execute your callback. For example::
 
         class Foo(object):
             def start(self):
@@ -62,18 +62,17 @@ to write a short function that does accept dt.  For Example::
             def callback(self, dt):
                 print('In callback')
 
-        # a Foo object is created, the method start is called,
-        # and the instance of foo is deleted
-        # Because nobody keep a reference to the instance returned from Foo(),
-        # the object will be collected by Python Garbage Collector. And you're
-        # callback will be never called.
+        # A Foo object is created and the method start is called.
+        # Because no reference is kept to the instance returned from Foo(),
+        # the object will be collected by the Python Garbage Collector and
+        # your callback will be never called.
         Foo().start()
 
-        # So you must do:
+        # So you should do the following and keep a reference to the instance
+        # of foo until you don't need it anymore!
         foo = Foo()
         foo.start()
 
-        # and keep the instance of foo, until you don't need it anymore!
 
 .. _schedule-before-frame:
 
@@ -89,8 +88,8 @@ from 1.0.5, you can use a timeout of -1::
     Clock.schedule_once(my_callback, -1) # call before the next frame
 
 The Clock will execute all the callbacks with a timeout of -1 before
-the next frame, even if you add a new callback with -1 from a running callback.
-However, :class:`Clock` has an iteration limit for these callbacks, it defaults
+the next frame even if you add a new callback with -1 from a running callback.
+However, :class:`Clock` has an iteration limit for these callbacks: it defaults
 to 10.
 
 If you schedule a callback that schedules a callback that schedules a .. etc
@@ -112,7 +111,7 @@ Triggered Events
 
 A triggered event is a way to defer a callback exactly like schedule_once(),
 but with some added convenience. The callback will only be scheduled once per
-frame, even if you call the trigger twice (or more). This is not the case
+frame even if you call the trigger twice (or more). This is not the case
 with :func:`Clock.schedule_once`::
 
     # will run the callback twice before the next frame
@@ -150,8 +149,8 @@ Even if x and y changes within one frame, the callback is only run once.
 
 .. note::
 
-    :func:`Clock.create_trigger` also has a timeout parameter that behaves
-    exactly like :func:`Clock.schedule_once`.
+    :func:`ClockBase.create_trigger` also has a timeout parameter that behaves
+    exactly like :func:`ClockBase.schedule_once`.
 
 '''
 
@@ -321,7 +320,7 @@ class ClockEvent(object):
 
 
 class ClockBase(_ClockBase):
-    '''A clock object with event support
+    '''A clock object with event support.
     '''
     __slots__ = ('_dt', '_last_fps_tick', '_last_tick', '_fps', '_rfps',
                  '_start_tick', '_fps_counter', '_rfps_counter', '_events',
@@ -350,13 +349,15 @@ class ClockBase(_ClockBase):
 
     @property
     def frametime(self):
-        '''Time spent between last frame and current frame (in seconds)
+        '''Time spent between the last frame and the current frame
+        (in seconds).
         '''
         return self._dt
 
     def tick(self):
-        '''Advance clock to the next step. Must be called every frame.
-        The default clock have the tick() function called by Kivy'''
+        '''Advance the clock to the next step. Must be called every frame.
+        The default clock has a tick() function called by the core Kivy
+        framework.'''
 
         self._release_references()
         if self._fps_counter % 100 == 0:
@@ -397,13 +398,13 @@ class ClockBase(_ClockBase):
         return self._dt
 
     def tick_draw(self):
-        '''Tick the drawing counter
+        '''Tick the drawing counter.
         '''
         self._process_events_before_frame()
         self._rfps_counter += 1
 
     def get_fps(self):
-        '''Get the current average FPS calculated by the clock
+        '''Get the current average FPS calculated by the clock.
         '''
         return self._fps
 
@@ -412,16 +413,16 @@ class ClockBase(_ClockBase):
         This counter reflects the real framerate displayed on the screen.
 
         In contrast to get_fps(), this function returns a counter of the number
-        of frames, not an average of frames per second
+        of frames, not the average of frames per second.
         '''
         return self._rfps
 
     def get_time(self):
-        '''Get the last tick made by the clock'''
+        '''Get the last tick made by the clock.'''
         return self._last_tick
 
     def get_boottime(self):
-        '''Get time in seconds from the application start'''
+        '''Get the time in seconds from the application start.'''
         return self._last_tick - self._start_tick
 
     def create_trigger(self, callback, timeout=0):
@@ -454,7 +455,7 @@ class ClockBase(_ClockBase):
         return event
 
     def schedule_interval(self, callback, timeout):
-        '''Schedule an event to be called every <timeout> seconds'''
+        '''Schedule an event to be called every <timeout> seconds.'''
         if not callable(callback):
             raise ValueError('callback must be a callable, got %s' % callback)
         cid = _hash(callback)
@@ -535,12 +536,12 @@ class ClockBase(_ClockBase):
 
 def mainthread(func):
     '''Decorator that will schedule the call of the function in the mainthread.
-    It can be useful when you use :class:`~kivy.network.urlrequest.UrlRequest`,
+    It can be useful when you use :class:`~kivy.network.urlrequest.UrlRequest`
     or when you do Thread programming: you cannot do any OpenGL-related work in
     a thread.
 
-    Please note that this method will return directly, and no result can be
-    fetched::
+    Please note that this method will return directly and no result can be
+    returned::
 
         @mainthread
         def callback(self, *args):
@@ -558,7 +559,7 @@ def mainthread(func):
     return delayed_func
 
 if 'KIVY_DOC_INCLUDE' in environ:
-    #: Instance of the ClockBase, available for everybody
+    #: Instance of :class:`ClockBase`.
     Clock = None
 else:
     Clock = register_context('Clock', ClockBase)