Merge branch 'master' of /home/kris/workspace/compiz

Conflicts:
	include/core/window.h
	plugins/composite/include/composite/composite.h

15 files changed, 228 insertions, 25 deletions

diff --git a/include/core/action.h b/include/core/action.h
index e24a6d1..006ba30 100644
--- a/include/core/action.h
+++ b/include/core/action.h
@@ -55,6 +55,9 @@ class PrivateAction;
 
 #define CompNoMask         (1 << 25)
 
+/**
+ * Context of an event occuring.
+ */
 class CompAction {
     public:
 	typedef enum {
@@ -72,7 +75,10 @@ class CompAction {
 	    StateAutoGrab    = 1 << 11,
 	    StateNoEdgeDelay = 1 << 12
 	} StateEnum;
-
+	
+	/**
+	 * Type of event a CompAction is bound to.
+	 */
 	typedef enum {
 	    BindingTypeNone       = 0,
 	    BindingTypeKey        = 1 << 0,
diff --git a/include/core/icon.h b/include/core/icon.h
index c0b9027..6f7a637 100644
--- a/include/core/icon.h
+++ b/include/core/icon.h
@@ -32,11 +32,17 @@
 
 class CompScreen;
 
+///
+/// Wraps an application icon pixel map and it's meta information (such as dimensions)
+///
 class CompIcon : public CompSize {
     public:
 	CompIcon (CompScreen *screen, unsigned width, unsigned int height);
 	~CompIcon ();
-
+	
+	///
+	/// Gets a pointer to the pixel data for this icon.
+	///
 	unsigned char* data ();
 
     private:
diff --git a/include/core/match.h b/include/core/match.h
index de26b5a..ba9c7f2 100644
--- a/include/core/match.h
+++ b/include/core/match.h
@@ -34,9 +34,16 @@ class PrivateMatch;
 class CompWindow;
 class CompDisplay;
 
+/**
+ * Matches windows based on properties similar to regular expressions.
+ * TODO how do you get the list of windows that match it?
+ */
 class CompMatch {
     public:
-
+    
+    /**
+     * TODO
+     */
 	class Expression {
 	    public:
 		virtual ~Expression () {};
diff --git a/include/core/modifierhandler.h b/include/core/modifierhandler.h
index 5620ce8..72c4b1e 100644
--- a/include/core/modifierhandler.h
+++ b/include/core/modifierhandler.h
@@ -28,6 +28,9 @@
 
 #include <core/core.h>
 
+/**
+ * TODO
+ */
 class ModifierHandler
 {
     public:
diff --git a/include/core/option.h b/include/core/option.h
index 2d9ba5f..09cf033 100644
--- a/include/core/option.h
+++ b/include/core/option.h
@@ -39,7 +39,14 @@ class CompAction;
 class CompMatch;
 class CompScreen;
 
+/**
+ * A configuration option with boolean, int, float, String, Color, Key, Button,
+ * Edge, Bell, or List.
+ */
 class CompOption {
+	/**
+	 * Option data types
+	 */
     public:
 	typedef enum {
 	    TypeBool,
@@ -57,7 +64,10 @@ class CompOption {
 	    /* internal use only */
 	    TypeUnset
 	} Type;
-
+	
+	/**
+	 * A value of an Option
+	 */
 	class Value {
 	    public:
 		typedef std::vector<Value> Vector;
@@ -116,7 +126,10 @@ class CompOption {
 	    private:
 		PrivateValue *priv;
 	};
-
+	
+	/**
+	 * TODO
+	 */
 	class Restriction {
 	    public:
 		Restriction ();
@@ -141,7 +154,10 @@ class CompOption {
 	};
 
 	typedef std::vector<CompOption> Vector;
-
+	
+	/**
+	 * TODO
+	 */
 	class Class {
 	    public:
 		virtual Vector & getOptions () = 0;
diff --git a/include/core/output.h b/include/core/output.h
index b925c90..093a822 100644
--- a/include/core/output.h
+++ b/include/core/output.h
@@ -31,6 +31,9 @@
 #include <core/core.h>
 #include <core/rect.h>
 
+///
+/// Output to a device from Compiz
+///
 class CompOutput : public CompRect {
 
     public:
diff --git a/include/core/plugin.h b/include/core/plugin.h
index 8c0581d..3fc3da5 100644
--- a/include/core/plugin.h
+++ b/include/core/plugin.h
@@ -73,6 +73,11 @@ union CompPrivate {
     void	  *(*fptr) (void);
 };
 
+/**
+ * Base plug-in interface for Compiz. All plugins must implement this
+ * interface, which provides basics for loading, unloading, options,
+ * and linking together the plugin and Screen(s).
+ */
 class CompPlugin {
     public:
 	class VTable {
@@ -82,7 +87,10 @@ class CompPlugin {
 
 		void initVTable (CompString         name,
 				 CompPlugin::VTable **self = NULL);
-
+		
+		/**
+		 * Gets the name of this compiz plugin
+		 */
 		const CompString name () const;
 
 		virtual bool init () = 0;
@@ -106,6 +114,9 @@ class CompPlugin {
 		VTable       **mSelf;
         };
 
+    /**
+     * TODO (or not?)
+     */
 	template <typename T, typename T2>
 	class VTableForScreenAndWindow : public VTable {
 	    bool initScreen (CompScreen *s);
@@ -121,6 +132,9 @@ class CompPlugin {
 	    bool setOption (const CompString &name, CompOption::Value &value);
 	};
 
+    /**
+     * TODO (or not?)
+     */
 	template <typename T>
 	class VTableForScreen : public VTable {
 	    bool initScreen (CompScreen *s);
@@ -131,7 +145,10 @@ class CompPlugin {
 
 	    bool setOption (const CompString &name, CompOption::Value &value);
 	};
-
+	
+	/**
+	 * Interface for matching plugins by name.
+	 */
 	struct cmpStr
 	{
 	    bool operator () (const char *a, const char *b) const
@@ -157,23 +174,58 @@ class CompPlugin {
 	static bool windowInitPlugins (CompWindow *w);
 
 	static void windowFiniPlugins (CompWindow *w);
-
+	
+	/**
+	 * Finds a plugin by name. (TODO Does it have to be loaded?)
+	 */
 	static CompPlugin *find (const char *name);
-
+	
+	/**
+	 * Load a compiz plugin. Loading a plugin that has
+	 * already been loaded will return the existing instance.
+	 */
 	static CompPlugin *load (const char *plugin);
-
+	
+	/**
+	 * Unload a compiz plugin. Unloading a plugin multiple times has no
+	 * effect, and you can't unload a plugin that hasn't been loaded already
+	 * with CompPlugin::load()
+	 */
 	static void unload (CompPlugin *p);
-
+	
+	/**
+	 * Adds a plugin onto the working set of active plugins. If the plugin fails to initPlugin
+	 * this will return false and the plugin will not be added to the working set.
+	 */
 	static bool push (CompPlugin *p);
-
+	
+	/**
+	 * Removes the last activated plugin with CompPlugin::push() and returns
+	 * the removed plugin, or NULL if there was none.
+	 */
 	static CompPlugin *pop (void);
-
+	
+	/**
+	 * Gets a list of the working set of plugins that have been CompPlugin::push() but not
+	 * CompPlugin::pop()'d.
+	 */
 	static List & getPlugins ();
-
+	
+	/**
+	 * Gets a list of the names of all the known plugins, including plugins that may
+	 * have already been loaded.
+	 */
 	static std::list<CompString> availablePlugins ();
-
+	
+	/**
+	 * Gets the Application Binary Interface (ABI) version of a (un)loaded plugin.
+	 */
 	static int getPluginABI (const char *name);
-
+	
+	/**
+	 * Verifies a signature to ensure that the plugin conforms to the Application Binary
+	 * Interface (ABI) 
+	 */
 	static bool checkPluginABI (const char *name,
 				    int	        abi);
 
diff --git a/include/core/pluginclasses.h b/include/core/pluginclasses.h
index 0122a63..ae1a824 100644
--- a/include/core/pluginclasses.h
+++ b/include/core/pluginclasses.h
@@ -30,6 +30,7 @@
 
 #include <vector>
 
+
 class PluginClassIndex {
     public:
 	PluginClassIndex () : index ((unsigned)~0), refCount (0),
diff --git a/include/core/point.h b/include/core/point.h
index 8e799f0..89f4e68 100644
--- a/include/core/point.h
+++ b/include/core/point.h
@@ -29,17 +29,39 @@
 #include <vector>
 #include <list>
 
+///
+/// A 2D coordinate (likely in screen space) that can only be mutated
+/// through set() methods, since it's data members are private.
+///
 class CompPoint {
 
     public:
 	CompPoint ();
 	CompPoint (int, int);
-
+	
+	///
+	/// Get the x coordinate of this point
+	///
 	int x () const;
+	
+	///
+	/// Get the y coordinate of this point
+	///
 	int y () const;
-
+	
+	///
+	/// Set the x and y coordinate of this point
+	///
 	void set (int, int);
+	
+	///
+	/// Set the x coordinate of this point
+	///
 	void setX (int);
+	
+	///
+	/// Set the y coordinate of this point
+	///
 	void setY (int);
 
 	bool operator== (const CompPoint &) const;
diff --git a/include/core/rect.h b/include/core/rect.h
index 4bca23c..df03fe6 100644
--- a/include/core/rect.h
+++ b/include/core/rect.h
@@ -26,6 +26,10 @@
 #ifndef _COMPRECT_H
 #define _COMPRECT_H
 
+///
+/// A 2D rectangle, which is likely in screen space. It's data is
+/// isolated and can only be mutated with set() methods.
+///
 class CompRect {
 
     public:
diff --git a/include/core/region.h b/include/core/region.h
index e71949b..87c10b6 100644
--- a/include/core/region.h
+++ b/include/core/region.h
@@ -34,6 +34,10 @@
 
 class PrivateRegion;
 
+///
+/// A 2D region with an (x,y) position and (width, height) dimensions similar to an XRegion.
+/// It's data membmers are private and  must be mutated with set() methods.
+///
 class CompRegion {
     public:
 	typedef std::vector<CompRegion> List;
diff --git a/include/core/screen.h b/include/core/screen.h
index eb6332d..d4ae692 100644
--- a/include/core/screen.h
+++ b/include/core/screen.h
@@ -67,6 +67,9 @@ typedef boost::function<void (const char *)> FileWatchCallBack;
 typedef int CompFileWatchHandle;
 typedef int CompWatchFdHandle;
 
+/**
+ * Information needed to invoke a CallBack when a file changes.
+ */
 struct CompFileWatch {
     CompString		path;
     int			mask;
@@ -78,6 +81,9 @@ typedef std::list<CompFileWatch *> CompFileWatchList;
 #define ACTIVE_WINDOW_HISTORY_SIZE 64
 #define ACTIVE_WINDOW_HISTORY_NUM  32
 
+/**
+ * Information about the last activity with a window.
+ */
 struct CompActiveWindowHistory {
     Window id[ACTIVE_WINDOW_HISTORY_SIZE];
     int    x;
@@ -85,6 +91,9 @@ struct CompActiveWindowHistory {
     int    activeNum;
 };
 
+/**
+ * Interface to an abstract screen.
+ */
 class ScreenInterface : public WrapableInterface<CompScreen, ScreenInterface> {
     public:
 	virtual void fileWatchAdded (CompFileWatch *fw);
@@ -125,7 +134,10 @@ class ScreenInterface : public WrapableInterface<CompScreen, ScreenInterface> {
 	virtual void addSupportedAtoms (std::vector<Atom>& atoms);
 };
 
-
+/**
+ * A wrapping of the X display screen. This takes care of communication to the
+ * X server.
+ */
 class CompScreen :
     public CompSize,
     public WrapableHandler<ScreenInterface, 18>,
diff --git a/include/core/size.h b/include/core/size.h
index 62d6dba..5ed56fc 100644
--- a/include/core/size.h
+++ b/include/core/size.h
@@ -29,6 +29,10 @@
 #include <vector>
 #include <list>
 
+///
+/// A 2D size (likely in screen space) that can only be mutated with set() methods,
+/// since it'd data members are private.
+///
 class CompSize {
 
     public:
diff --git a/include/core/timer.h b/include/core/timer.h
index d159999..93c47e0 100644
--- a/include/core/timer.h
+++ b/include/core/timer.h
@@ -28,28 +28,69 @@
 
 #include <boost/function.hpp>
 
+/**
+ * A simple timer for use with invoking a CallBack during a timed duration.
+ */
 class CompTimer {
 
     public:
 
 	typedef boost::function<bool ()> CallBack;
-
+	
+	/**
+	 * Empty constructor setting everything to zero and NULL.
+	 */
 	CompTimer ();
+	
+	/**
+	 * Frees the private data for this timer and any information about it's
+	 * context.
+	 */
 	~CompTimer ();
-
+	
+	/**
+	 * Checks if this timer is active and will have it's CallBack invoked.
+	 */
 	bool active ();
 	unsigned int minTime ();
 	unsigned int maxTime ();
 	unsigned int minLeft ();
 	unsigned int maxLeft ();
-
+	
+	/**
+	 * Sets the timing durations of this timer.
+	 */
 	void setTimes (unsigned int min, unsigned int max = 0);
+	
+	/**
+	 * Sets the callback function to invoke for this timer. This defaults
+	 * to NULL.
+	 */
 	void setCallback (CallBack callback);
-
+	
+	/**
+	 * Starts this timer without modifying any of it's parameters. The timer is
+	 * stop()'d before this occurs.
+	 */
 	void start ();
+	
+	/**
+	 * Starts this timer setting the paramters with setTimes(). The timer is stop()'d
+	 * before this occurs.
+	 */
 	void start (unsigned int min, unsigned int max = 0);
+	
+	/**
+	 * Starts this timer setting the parameters with setTimes() and setCallback(). The timer is
+	 * stop()'d before this occurs.
+	 */
 	void start (CallBack callback,
 		    unsigned int min, unsigned int max = 0);
+	
+	/**
+	 * Stops this timer. After this the timer should not be active() and it's CallBack shouldn't
+	 * be invoked.
+	 */
 	void stop ();
 
 	friend class CompScreen;
diff --git a/include/core/window.h b/include/core/window.h
index 056b923..2338620 100644
--- a/include/core/window.h
+++ b/include/core/window.h
@@ -155,6 +155,9 @@ struct CompStartupSequence;
 #define CompWindowGrabResizeMask      (1 << 3)
 #define CompWindowGrabExternalAppMask (1 << 4)
 
+/**
+ * TODO
+ */
 enum CompStackingUpdateMode {
     CompStackingUpdateModeNone = 0,
     CompStackingUpdateModeNormal,
@@ -163,6 +166,9 @@ enum CompStackingUpdateMode {
     CompStackingUpdateModeInitialMapDeniedFocus
 };
 
+/**
+ * TODO
+ */
 enum CompWindowNotify {
    CompWindowNotifyMap,
    CompWindowNotifyUnmap,
@@ -187,6 +193,9 @@ enum CompWindowNotify {
    CompWindowNotifyBeforeMap
 };
 
+/**
+ * TODO
+ */
 struct CompWindowExtents {
     int left;
     int right;
@@ -194,6 +203,9 @@ struct CompWindowExtents {
     int bottom;
 };
 
+/**
+ * TODO
+ */
 struct CompStruts {
     XRectangle left;
     XRectangle right;
@@ -201,6 +213,9 @@ struct CompStruts {
     XRectangle bottom;
 };
 
+/**
+ * TODO
+ */
 class WindowInterface : public WrapableInterface<CompWindow, WindowInterface>
 {
     public:
@@ -233,12 +248,19 @@ class WindowInterface : public WrapableInterface<CompWindow, WindowInterface>
 	virtual bool isFocussable ();
 };
 
+/**
+ * An Window object that wraps an X window. This handles snychronization of
+ * window state, geometry, etc. between Compiz and the X server. 
+ */
 class CompWindow :
     public WrapableHandler<WindowInterface, 15>,
     public PluginClassStorage
 {
     public:
-
+    
+    /**
+     * A mutable object about the dimensions and location of a CompWindow.
+     */
 	class Geometry : public CompRect
     {
 	    public: