Created attachment 216152 [details] [review]
tutorials python: commented samples and more detailed pages for windows samples

Review of attachment 216152 [details] [review]:

Okay, I am pushing this patch to master.  If you could make the changes made below, and attach another patch with the fixes, that would be great!

Thanks!

::: platform-demos/C/GtkApplicationWindow.py.page
@@ +31,3 @@
+  </p>
+  <list>
+    <item><p><code>self.set_default_size(200, 100)</code> sets the default size of the window to a width of <code>200</code> and a height of <code>100</code>; if instead of a positive number we pass <code>-1</code> we have the default size.</p></item>

omit the "self" or variable instance name here.  Just 'set_default_size'....
(One may choose not to create a separate class, so their instance variable names may differ, which could potentially cause confusion).

@@ +32,3 @@
+  <list>
+    <item><p><code>self.set_default_size(200, 100)</code> sets the default size of the window to a width of <code>200</code> and a height of <code>100</code>; if instead of a positive number we pass <code>-1</code> we have the default size.</p></item>
+    <item><p><code>self.set_position(Gtk.WindowPosition.CENTER)</code> centers the window. Other options are described in the <link href="http://developer.gnome.org/gtk3/3.4/gtk3-Standard-Enumerations.html#GtkWindowPosition">standard enumerations</link> (with the caveat that they should be changed on the model of Gtk.WindowPosition.CENTER).</p></item>

omit 'self'... just the method name is fine.

::: platform-demos/C/dialog.py.page
@@ +27,3 @@
+  </p>
+  <list>
+    <item><p>Instead of <code>dialog.set_modal(True)</code> we could have <code>dialog.set_modal(False)</code> followed by <code>dialog.set_destroy_with_parent(True)</code> that would destroy the dialog window if the main window is closed.</p></item>

again, 'dialog' is the specific variable name in this code, so best omit it and only give the method name...

@@ +28,3 @@
+  <list>
+    <item><p>Instead of <code>dialog.set_modal(True)</code> we could have <code>dialog.set_modal(False)</code> followed by <code>dialog.set_destroy_with_parent(True)</code> that would destroy the dialog window if the main window is closed.</p></item>
+    <item><p><code>dialog.add_button(button_text="The Answer", response_id=42)</code>, where <code>42</code> is any integer, is an alternative to <code>dialog.add_button(button_text="text", response_id=Gtk.ResponseType.RESPONSE)</code>, where <code>RESPONSE</code> could be one of <code>OK, CANCEL, CLOSE, YES, NO, APPLY, HELP</code>, which in turn correspond to the integers <code>-5, -6,..., -11</code>.</p></item>

same comment as above about 'dialog'

::: platform-demos/C/messagedialog.py.page
@@ +31,3 @@
+    <item><p>In the constructor of MessageDialog we could set buttons as any of <code>Gtk.ButtonsType.NONE, Gtk.ButtonsType.OK, Gtk.ButtonsType.CLOSE, Gtk.ButtonsType.CANCEL, Gtk.ButtonsType.YES_NO, Gtk.ButtonsType.OK_CANCEL</code>, or any button using <code>messagedialog.add_button()</code> as in Gtk.Dialog.</p></item>
+    <item><p>We could substitute the default image of the MessageDialog with another image using</p>
+    <code mime="text/x-python" style="numbered">

remove 'style="numbered"' for code snippets.

@@ +37,3 @@
+messagedialog.set_image(image)</code>
+    <p>where <code>Gtk.STOCK_CAPS_LOCK_WARNING</code> is any image from <link href="http://developer.gnome.org/gtk3/3.4/gtk3-Stock-Items.html">Stock Items</link>. We could also set any image as in the Image widget, as <code>image.set_from_file("filename.png")</code>.</p></item>
+    <item><p><code>messagedialog.format_secondary_text("some secondary message")</code> sets a secondary message. The primary text becomes bold.</p></item>

omit 'messagedialog' variable name.

::: platform-demos/C/samples/aboutdialog.py
@@ +19,1 @@
+    # callback function for the signal "about" from the action in the menu of the main window

This is actually the callback function for the about_action's "activate" signal.

::: platform-demos/C/window.py.page
@@ +42,3 @@
+  <list>
+    <item><p><code>window = Gtk.Window(application=self, title="Welcome to GNOME")</code> sets the title as well, without the need for the line <code>window.set_title("Welcome to GNOME")</code>.</p></item>
+    <item><p><code>window.set_default_size(200, 100)</code> sets the default size of the window to a width of <code>200</code> and a height of <code>100</code>; if instead of a positive number we pass <code>-1</code> we have the default size.</p></item>

omit 'window' variable name.

@@ +43,3 @@
+    <item><p><code>window = Gtk.Window(application=self, title="Welcome to GNOME")</code> sets the title as well, without the need for the line <code>window.set_title("Welcome to GNOME")</code>.</p></item>
+    <item><p><code>window.set_default_size(200, 100)</code> sets the default size of the window to a width of <code>200</code> and a height of <code>100</code>; if instead of a positive number we pass <code>-1</code> we have the default size.</p></item>
+    <item><p><code>window.set_position(Gtk.WindowPosition.CENTER)</code> centers the window. Other options are described in the <link href="http://developer.gnome.org/gtk3/3.4/gtk3-Standard-Enumerations.html#GtkWindowPosition">standard enumerations</link> (with the caveat that they should be changed on the model of Gtk.WindowPosition.CENTER).</p></item>

omit 'window' variable name.

pushed to master: http://git.gnome.org/browse/gnome-devel-docs/commit/?id=7b48c07ba0d032e14649f1b41a1c6b86a9862c44

Created attachment 216428 [details] [review]
patch

names of the variables removed

Review of attachment 216428 [details] [review]:

Thanks!

http://git.gnome.org/browse/gnome-devel-docs/commit/?id=0ff11f7d32fdaeb8e568f9f925878a5b848e39cc

Review of attachment 216152 [details] [review]:

.

Created attachment 216430 [details] [review]
patch

* Pages now have sections
* aboutdialog.py comments are correct

Created attachment 216433 [details] [review]
patch

"API References" instead of "References"

Review of attachment 216430 [details] [review]:

pushed to master: http://git.gnome.org/browse/gnome-devel-docs/commit/?id=8530651095d2cff7fd8d8a38b179ecb420664f71

Review of attachment 216433 [details] [review]:

commit: http://git.gnome.org/browse/gnome-devel-docs/commit/?id=18ae90558dd7b16637f8bfc376e999a9438dbdb5