diff --git a/plasma.cpp b/plasma.cpp
index 61e8f9a47..5bdf29e66 100644
--- a/plasma.cpp
+++ b/plasma.cpp
@@ -33,13 +33,15 @@ int uniqueId()
     return ++plasmaIds;
 }
 
-Direction edgeToPopupDirection(ScreenEdge edge)
+Direction locationToDirection(Location location)
 {
-    switch (edge)
+    switch (location)
     {
         case Floating:
         case Desktop:
         case TopEdge:
+            //TODO: should we be smarter for floating and planer?
+            //      perhaps we should take a QRect and/or QPos as well?
             return Down;
         case BottomEdge:
             return Up;
@@ -48,7 +50,8 @@ Direction edgeToPopupDirection(ScreenEdge edge)
         case RightEdge:
             return Left;
     }
-	return Down;
+
+    return Down;
 }
 
 } // Plasma namespace
diff --git a/plasma.h b/plasma.h
index 6cafa5301..7cb02c86a 100644
--- a/plasma.h
+++ b/plasma.h
@@ -27,22 +27,56 @@
 namespace Plasma
 {
 
-enum AppletConstraint { NoConstraint = 0,
-                        Width = 1,
-                        Height = 2,
-                        MaxAppletConstraint = Height };
+/**
+ * The FormFactor enumeration describes how a Plasma::Applet should arrange
+ * itself. The value is derived from the container managing the Applet
+ * (e.g. in Plasma, a Corona on the desktop or on a panel).
+ **/
+enum FormFactor { Planar = 0  /**< The applet lives in a plane and has two
+                                   degrees of freedom to grow. Optimize for
+                                   desktop, laptop or tablet usage: a high
+                                   resolution screen 1-3 feet distant from the
+                                   viewer. */,
+                  MediaCenter /**< As with Planar, the applet lives in a plane
+                                   but the interface should be optimized for
+                                   medium-to-high resolution screens that are
+                                   5-15 feet distant from the viewer. Sometimes
+                                   referred to as a "ten foot interface".*/,
+                  Horizontal  /**< The applet is constrained vertically, but
+                                   can expand horizontally. */,
+                  Vertical    /**< The applet is contrained horizontally, but
+                                   can expand vertically. */
+                };
 
-enum Direction { Down = 0,
-                 Up,
-                 Left,
-                 Right };
+/**
+ * The Direction enumeration describes in which direction, relative to the
+ * Applet (and its managing container), popup menus, expanders, balloons,
+ * message boxes, arrows and other such visually associated widgets should
+ * appear in. This is usually the oposite of the Location.
+ **/
+enum Direction { Down = 0 /**< Display downards */ ,
+                 Up       /**< Display upwards */,
+                 Left     /**< Display to the left */,
+                 Right    /**< Display to the right */
+               };
 
-enum ScreenEdge { Floating = 0, Desktop,
-                  TopEdge, BottomEdge, LeftEdge, RightEdge };
+/**
+ * The Location enumeration describes where on screen an element, such as an
+ * Applet or its managing container, is positioned on the screen.
+ **/
+enum Location { Floating = 0 /**< Free floating. Neither geometry or z-ordering
+                                  is described precisely by this value. */,
+                Desktop      /**< On the planar desktop layer, extending across
+                                  the full screen from edge to edge */,
+                TopEdge      /**< Along the top of the screen*/,
+                BottomEdge   /**< Along the bottom of the screen*/,
+                LeftEdge     /**< Along the left side of the screen */,
+                RightEdge    /**< Along the right side of the screen */
+              };
 
 PLASMA_EXPORT void setMinId(int minId);
 PLASMA_EXPORT int uniqueId();
-PLASMA_EXPORT Direction edgeToPopupDirection(ScreenEdge edge);
+PLASMA_EXPORT Direction locationToDirection(Location location);
 
 } // Plasma namespace