Added comments and cleaned up code

git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@47 ddfedd41-794f-dd11-ae45-00112f111e67

diff --git a/src/window.c b/src/window.c
index 8922d8f3d1e116d168bf45c7ee9655878af750da..c1a79eeb7d319da6aa4a5a40a5531108d4328f8f 100644 (file)
--- a/src/window.c
+++ b/src/window.c
@@ -541,80 +541,7 @@ glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype,
        return win;
 }
 
-/**
- * glk_window_close:
- * @win: Window to close.
- * @result: Pointer to a #stream_result_t in which to store the write count.
- *
- * Closes @win, which is pretty much exactly the opposite of opening a window.
- * It is legal to close all your windows, or to close the root window (which is
- * the same thing.) 
- *
- * The @result argument is filled with the output character count of the window
- * stream. See <link linkend="chimara-Streams">Streams</link> and <link
- * linkend="chimara-Closing-Streams">Closing Streams</link>.
- * 
- * When you close a window (and it is not the root window), the other window
- * in its pair takes over all the freed-up area. Let's close D, in the current
- * example:
- * <mediaobject><textobject><phrase>Screen shot 10</phrase></textobject>
- * </mediaobject>
- * 
- * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right
- * split has gone with it. The other size constraints are unchanged; O2 is
- * still committed to giving its upper child two rows, as measured in the font
- * of O2's key window, which is C. Conveniently, O2's upper child is C, just as
- * it was before we created D. In fact, now that D is gone, everything is back
- * to the way it was before we created D.
- * 
- * But what if we had closed C instead of D? We would have gotten this:
- * <mediaobject><textobject><phrase>Screen shot 11</phrase></textobject>
- * </mediaobject>
- * 
- * Again, O3 is gone. But D has collapsed to zero height. This is because its
- * height is controlled by O2, and O2's key window was C, and C is now gone. O2
- * no longer has a key window at all, so it cannot compute a height for its
- * upper child, so it defaults to zero.
- * 
- * <note><para>
- *   This may seem to be an inconvenient choice. That is deliberate. You should
- *   not leave a pair window with no key, and the zero-height default reminds
- *   you not to. You can use glk_window_set_arrangement() to set a new split
- *   measurement and key window. See <link 
- *   linkend="chimara-Changing-Window-Constraints">Changing Window
- *   Constraints</link>.
- * </para></note>
- */
-
-static void
-dump_window_tree(GNode *node)
-{
-       if(node == NULL) {
-               g_printerr("NULL");
-               return;
-       }
-       g_printerr("[");
-       switch(((winid_t)node->data)->type) {
-               case wintype_Pair:
-                       g_printerr("Pair ");
-                       dump_window_tree(node->children);
-                       dump_window_tree(node->children->next);
-                       g_printerr("]");
-                       break;
-               case wintype_TextBuffer:
-                       g_printerr("Buffer]");
-                       break;
-               case wintype_TextGrid:
-                       g_printerr("Grid]");
-                       break;
-               case wintype_Blank:
-                       g_printerr("Blank]");
-                       break;
-               default:
-                       g_printerr("Fucked up - %d]", ((winid_t)node->data)->type);
-       }
-}
-
+/* Internal function: close the window streams of this window and all its children */
 static void
 close_window_streams_below(winid_t win, stream_result_t *result)
 {
@@ -625,6 +552,7 @@ close_window_streams_below(winid_t win, stream_result_t *result)
        stream_close_common(win->window_stream, result);
 }
 
+/* Internal function: destroy this window's GTK widgets and those of all its children */
 static void
 destroy_widgets_below(winid_t win)
 {
@@ -655,6 +583,7 @@ destroy_widgets_below(winid_t win)
        }
 }
 
+/* Internal function: free the winid_t structure of this window and those of all its children */
 static void
 free_winids_below(winid_t win)
 {
@@ -666,6 +595,50 @@ free_winids_below(winid_t win)
        g_free(win);
 }
 
+/**
+ * glk_window_close:
+ * @win: Window to close.
+ * @result: Pointer to a #stream_result_t in which to store the write count.
+ *
+ * Closes @win, which is pretty much exactly the opposite of opening a window.
+ * It is legal to close all your windows, or to close the root window (which is
+ * the same thing.) 
+ *
+ * The @result argument is filled with the output character count of the window
+ * stream. See <link linkend="chimara-Streams">Streams</link> and <link
+ * linkend="chimara-Closing-Streams">Closing Streams</link>.
+ * 
+ * When you close a window (and it is not the root window), the other window
+ * in its pair takes over all the freed-up area. Let's close D, in the current
+ * example:
+ * <mediaobject><textobject><phrase>Screen shot 10</phrase></textobject>
+ * </mediaobject>
+ * 
+ * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right
+ * split has gone with it. The other size constraints are unchanged; O2 is
+ * still committed to giving its upper child two rows, as measured in the font
+ * of O2's key window, which is C. Conveniently, O2's upper child is C, just as
+ * it was before we created D. In fact, now that D is gone, everything is back
+ * to the way it was before we created D.
+ * 
+ * But what if we had closed C instead of D? We would have gotten this:
+ * <mediaobject><textobject><phrase>Screen shot 11</phrase></textobject>
+ * </mediaobject>
+ * 
+ * Again, O3 is gone. But D has collapsed to zero height. This is because its
+ * height is controlled by O2, and O2's key window was C, and C is now gone. O2
+ * no longer has a key window at all, so it cannot compute a height for its
+ * upper child, so it defaults to zero.
+ * 
+ * <note><para>
+ *   This may seem to be an inconvenient choice. That is deliberate. You should
+ *   not leave a pair window with no key, and the zero-height default reminds
+ *   you not to. You can use glk_window_set_arrangement() to set a new split
+ *   measurement and key window. See <link 
+ *   linkend="chimara-Changing-Window-Constraints">Changing Window
+ *   Constraints</link>.
+ * </para></note>
+ */
 void
 glk_window_close(winid_t win, stream_result_t *result)
 {