From b55dbe10bb5ff568066f03bf6c421c79305e79df Mon Sep 17 00:00:00 2001
From: Thomas Thurman <tthurman@gnome.org>
Date: Fri, 30 May 2008 22:27:43 +0000
Subject: [PATCH] commenting

2008-05-30  Thomas Thurman  <tthurman@gnome.org>

        * src/core/window-props.h: commenting


svn path=/trunk/; revision=3743
---
 ChangeLog               |  4 +++
 src/core/window-props.h | 77 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index c304e5450..e39640989 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-05-30  Thomas Thurman  <tthurman@gnome.org>
+
+        * src/core/window-props.h: commenting
+
 2008-05-28  Thomas Thurman  <tthurman@gnome.org>
 
         * src/core/prefs.c (handle_preference_update_string,
diff --git a/src/core/window-props.h b/src/core/window-props.h
index 533bcd7a1..ac4d17af6 100644
--- a/src/core/window-props.h
+++ b/src/core/window-props.h
@@ -1,6 +1,14 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* MetaWindow property handling */
+/**
+ * \file window-props.c    MetaWindow property handling
+ *
+ * A system which can inspect sets of properties of given windows
+ * and take appropriate action given their values.
+ *
+ * Note that all the meta_window_reload_propert* functions require a
+ * round trip to the server.
+ */
 
 /* 
  * Copyright (C) 2001, 2002 Red Hat, Inc.
@@ -26,24 +34,91 @@
 
 #include "window-private.h"
 
+/**
+ * Requests the current values of a set of properties for a given
+ * window from the server, and deals with them appropriately.
+ * Does not return them to the caller (they've been dealt with!)
+ *
+ * \param window     The window.
+ * \param property   A single X atom.
+ */
 void meta_window_reload_property   (MetaWindow *window,
                                     Atom        property);
+
+
+/**
+ * Requests the current values of a set of properties for a given
+ * window from the server, and deals with them appropriately.
+ * Does not return them to the caller (they've been dealt with!)
+ *
+ * \param window      The window.
+ * \param properties  A pointer to a list of X atoms, "n_properties" long.
+ * \param n_properties  The length of the properties list.
+ */
 void meta_window_reload_properties (MetaWindow *window,
                                     const Atom *properties,
                                     int         n_properties);
+
+/**
+ * Requests the current values of a set of properties for a given
+ * window from the server, and deals with them appropriately.
+ * Does not return them to the caller (they've been dealt with!)
+ *
+ * \param window     A window on the same display as the one we're
+ *                   investigating (only used to find the display)
+ * \param xwindow    The X handle for the window.
+ * \param property   A single X atom.
+ */
 void meta_window_reload_property_from_xwindow
                                    (MetaWindow *window,
                                     Window      xwindow,
                                     Atom        property);
+
+/**
+ * Requests the current values of a set of properties for a given
+ * window from the server, and deals with them appropriately.
+ * Does not return them to the caller (they've been dealt with!)
+ *
+ * \param window     A window on the same display as the one we're
+ *                   investigating (only used to find the display)
+ * \param xwindow     The X handle for the window.
+ * \param properties  A pointer to a list of X atoms, "n_properties" long.
+ * \param n_properties  The length of the properties list.
+ */
 void meta_window_reload_properties_from_xwindow
                                    (MetaWindow *window,
                                     Window      xwindow,
                                     const Atom *properties,
                                     int         n_properties);
 
+/**
+ * Initialises the hooks used for the reload_propert* functions
+ * on a particular display, and stores a pointer to them in the
+ * display.
+ *
+ * \param display  The display.
+ */
 void meta_display_init_window_prop_hooks (MetaDisplay *display);
+
+/**
+ * Frees the hooks used for the reload_propert* functions
+ * for a particular display.
+ *
+ * \param display  The display.
+ */
 void meta_display_free_window_prop_hooks (MetaDisplay *display);
 
+/**
+ * Sets the size hints for a window.  This happens when a
+ * WM_NORMAL_HINTS property is set on a window, but it is public
+ * because the size hints are set to defaults when a window is
+ * created.  See
+ * http://tronche.com/gui/x/icccm/sec-4.html#WM_NORMAL_HINTS
+ * for the X details.
+ *
+ * \param window   The window to set the size hints on.
+ * \param hints    Either some X size hints, or NULL for default.
+ */
 void meta_set_normal_hints (MetaWindow *window,
 			    XSizeHints *hints);