[pyclutter] examples: Document the rounded-rectangle code

[Emmanuele Bassi <ebassi src gnome org>]

commit 90c43fc05f565bf5b0dad41364ac7ffe6eb75be0
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Mon Apr 13 12:23:06 2015 +0100

    examples: Document the rounded-rectangle code

 examples/rounded-rectangle.py |   23 +++++++++++++++++------
 1 files changed, 17 insertions(+), 6 deletions(-)
---
diff --git a/examples/rounded-rectangle.py b/examples/rounded-rectangle.py
index 82605dc..3709ae8 100644
--- a/examples/rounded-rectangle.py
+++ b/examples/rounded-rectangle.py
@@ -3,6 +3,8 @@ import cairo
 from gi.repository import GObject
 from gi.repository import Clutter
 
+# The code for the rounded rectangle drawing is taken from the
+# Cairo documentation
 def draw_content(canvas, cr, surface_width, surface_height):
     padding = 2
     x = padding
@@ -14,16 +16,18 @@ def draw_content(canvas, cr, surface_width, surface_height):
     radius = corner_radius / aspect
     degrees = math.pi / 180
 
+    # Clear the contents of the canvas
     cr.save()
     cr.set_operator(cairo.OPERATOR_CLEAR)
     cr.paint()
     cr.restore()
 
+    # Draw each rounded corner
     cr.new_sub_path()
-    cr.arc(x + width - radius, y + radius, radius, -90 * degrees, 0 * degrees)
-    cr.arc(x + width - radius, y + height - radius, radius, 0 * degrees, 90 * degrees)
-    cr.arc(x + radius, y + height - radius, radius, 90 * degrees, 180 * degrees)
-    cr.arc(x + radius, y + radius, radius, 180 * degrees, 270 * degrees)
+    cr.arc(x + width - radius, y + radius,          radius, -90 * degrees,   0 * degrees)
+    cr.arc(x + width - radius, y + height - radius, radius,   0 * degrees,  90 * degrees)
+    cr.arc(x + radius,         y + height - radius, radius,  90 * degrees, 180 * degrees)
+    cr.arc(x + radius,         y + radius,          radius, 180 * degrees, 270 * degrees)
     cr.close_path()
 
     cr.set_source_rgb(0.5, 0.5, 1)
@@ -32,14 +36,20 @@ def draw_content(canvas, cr, surface_width, surface_height):
     return True
 
 if __name__ == '__main__':
+    # Create our stage
     stage = Clutter.Stage()
     stage.props.title = 'Rounded Rectangle'
     stage.props.background_color = Clutter.Color.get_static(Clutter.StaticColor.BLACK)
     stage.set_size(500, 500)
+    stage.connect('destroy', Clutter.main_quit)
     stage.show()
 
+    # The canvas used for drawing the rounded rectanglr
     canvas = Clutter.Canvas(width=300, height=300)
 
+    # The actor displaying the canvas content; the actor has the same
+    # preferred size as the content, but if it gets allocated more
+    # space, the content will be centered inside that allocation
     actor = Clutter.Actor(content=canvas,
                           content_gravity=Clutter.ContentGravity.CENTER,
                           request_mode=Clutter.RequestMode.CONTENT_SIZE)
@@ -48,6 +58,7 @@ if __name__ == '__main__':
     actor.add_constraint(Clutter.AlignConstraint(source=stage, align_axis=Clutter.AlignAxis.BOTH, 
factor=0.5))
     stage.add_child(actor)
 
+    # We use an explicit transition because we want to make it loop
     transition = Clutter.PropertyTransition('rotation-angle-y')
     transition.set_from(0)
     transition.set_to(360)
@@ -55,8 +66,8 @@ if __name__ == '__main__':
     transition.set_repeat_count(-1)
     actor.add_transition('rotateActor', transition)
 
-    stage.connect('destroy', Clutter.main_quit)
-
+    # Connect to the 'draw' signal before invalidating, so that the canvas
+    # gets drawn once
     canvas.connect('draw', draw_content)
     canvas.invalidate()