Function commenting marathon; more to come.

2008-01-06  Thomas Thurman  <tthurman@gnome.org>

        * src/core/display.c: Function commenting marathon; more to come.



svn path=/trunk/; revision=3506

ChangeLog

@@ -1,3 +1,7 @@
+2008-01-06  Thomas Thurman  <tthurman@gnome.org>
+
+        * src/core/display.c: Function commenting marathon; more to come.
+
 2008-01-02  Thomas Thurman  <tthurman@gnome.org>
 
 	* src/core/xprops.c (meta_prop_get_cardinal), src/core/compositor.c

src/core/display.c

@@ -80,6 +80,27 @@
          g == META_GRAB_OP_KEYBOARD_ESCAPING_DOCK   ||  \
          g == META_GRAB_OP_KEYBOARD_ESCAPING_GROUP)
 
+/*! \defgroup pings
+ * Sometimes we want to see whether a window is responding,
+ * so we send it a "ping" message and see whether it sends us back a "pong"
+ * message within a reasonable time. Here we have a system which lets us
+ * nominate one function to be called if we get the pong in time and another
+ * function if we don't. The system is rather more complicated than it needs
+ * to be, since we only ever use it to destroy windows which are asked to
+ * close themselves and don't do so within a reasonable amount of time, and
+ * therefore we always use the same callbacks. It's possible that we might
+ * use it for other things in future, or on the other hand we might decide
+ * that we're never going to do so and simplify it a bit.
+ */
+
+/*! Describes a ping on a window. When we send a ping to a window, we build
+ * one of these structs, and it eventually gets passed to the timeout function
+ * or to the function which handles the response from the window. If the window
+ * does or doesn't respond to the ping, we use this information to deal with
+ * these facts; we have a handler function for each.
+ *
+ * \ingroup pings
+ */
 typedef struct 
 {
   MetaDisplay *display;
@@ -127,6 +148,11 @@ static void    sanity_check_timestamps   (MetaDisplay *display,
 
 MetaGroup*     get_focussed_group (MetaDisplay *display);
 
+/*! Destructor for MetaPingData structs. Will destroy the
+ * event source for the struct as well.
+ *
+ * \ingroup pings
+ */
 static void
 ping_data_free (MetaPingData *ping_data)
 {
@@ -137,6 +163,15 @@ ping_data_free (MetaPingData *ping_data)
   g_free (ping_data);
 }
 
+/*! Frees every pending ping structure for the given X window on the
+ * given display. This means that we also destroy the timeouts.
+ *
+ * \param display The display the window appears on
+ * \param xwindow The X ID of the window whose pings we should remove
+ *
+ * \ingroup pings
+ *
+ */
 static void
 remove_pending_pings_for_window (MetaDisplay *display, Window xwindow)
 {
@@ -4049,14 +4084,31 @@ meta_display_set_cursor_theme (const char *theme,
 #endif
 }
 
+/*! Stores whether syncing is currently enabled.
+ */
 static gboolean is_syncing = FALSE;
 
+/*! Returns whether X synchronisation is currently enabled.
+ *
+ * \return true if we must wait for events whenever we send X requests;
+ * false otherwise.
+ *
+ * \bug This is *only* called by meta_display_open, but by that time
+ * we have already turned syncing on or off on startup, and we don't
+ * have any way to do so while Metacity is running, so it's rather
+ * pointless.
+ */
 gboolean
 meta_is_syncing (void)
 {
   return is_syncing;
 }
 
+/*! A handy way to turn on synchronisation on or off for every display.
+ *
+ * \bug Of course there is only one display ever anyway, so this can
+ * be rather hugely simplified.
+ */
 void
 meta_set_syncing (gboolean setting)
 {
@@ -4076,8 +4128,25 @@ meta_set_syncing (gboolean setting)
     }
 }
 
+/*! How long, in milliseconds, we should wait after pinging a window
+ * before deciding it's not going to get back to us.
+ */
 #define PING_TIMEOUT_DELAY 2250
 
+/*! Does whatever it is we decided to do when a window didn't respond
+ * to a ping. We also remove the ping from the display's list of
+ * pending pings. This function is called by the event loop when the timeout
+ * times out which we created at the start of the ping.
+ *
+ * \param data All the information about this ping. It is a MetaPingData
+ *             cast to a void* in order to be passable to a timeout function.
+ *             This function will also free this parameter.
+ *
+ * \return Always returns false, because this function is called as a
+ *         timeout and we don't want to run the timer again.
+ *
+ * \ingroup pings
+ */
 static gboolean
 meta_display_ping_timeout (gpointer data)
 {
@@ -4102,6 +4171,28 @@ meta_display_ping_timeout (gpointer data)
   return FALSE;
 }
 
+/*! Sends a ping request to a window. The window must respond to
+ * the request within a certain amount of time. If it does, we
+ * will call one callback; if the time passes and we haven't had
+ * a response, we call a different callback. The window must have
+ * the hint showing that it can respond to a ping; if it doesn't,
+ * we call the "got a response" callback immediately and return.
+ *
+ * \param display  The MetaDisplay that the window is on
+ * \param window   The MetaWindow to send the ping to
+ * \param timestamp The timestamp of the ping. Used for uniqueness.
+ *                  Cannot be CurrentTime; use a real timestamp!
+ * \param ping_reply_func The callback to call if we get a response.
+ * \param ping_timeout_func The callback to call if we don't get a response.
+ * \param user_data Arbitrary data that will be passed to the callback
+ *                  function. (In practice it's often a pointer to
+ *                  the window.)
+ *
+ * \bug This should probably be a method on windows, rather than displays
+ *      for one of their windows.
+ *
+ * \ingroup pings
+ */
 void
 meta_display_ping_window (MetaDisplay       *display,
 			  MetaWindow        *window,
@@ -4215,7 +4306,17 @@ process_request_frame_extents (MetaDisplay    *display,
   meta_XFree (hints);
 }
 
-/* process the pong from our ping */
+/*! Process the pong (the response message) from the ping we sent
+ * to the window. This involves removing the timeout, calling the
+ * reply handler function, and freeing memory.
+ *
+ * \param display  the display we got the pong from
+ * \param event    the XEvent which is a pong; we can tell which
+ *                 ping it corresponds to because it bears the
+ *                 same timestamp.
+ *
+ * \ingroup pings
+ */
 static void
 process_pong_message (MetaDisplay    *display,
                       XEvent         *event)
@@ -4260,6 +4361,17 @@ process_pong_message (MetaDisplay    *display,
     }
 }
 
+/*! Finds whether a window has any pings waiting on it.
+ *
+ * \param display The MetaDisplay of the window.
+ * \param window  The MetaWindow whose pings we want to know about.
+ *
+ * \return True if there is at least one ping which has been sent
+ *         to the window without getting a response; false otherwise.
+ *
+ * \bug This should probably be a method on windows, rather than displays
+ *      for one of their windows.
+ */
 gboolean
 meta_display_window_has_pending_pings (MetaDisplay *display,
 				       MetaWindow  *window)