From 454cbaa7cb05a06d355487c4b0cce0881c566618 Mon Sep 17 00:00:00 2001
From: Aaron Seigo <aseigo@kde.org>
Date: Mon, 13 Feb 2012 22:30:09 +0100
Subject: [PATCH] fix up constraintsEvent documentation

---
 applet.h | 10 ++++++++--
 plasma.h | 26 +++++++++-----------------
 2 files changed, 17 insertions(+), 19 deletions(-)

diff --git a/applet.h b/applet.h
index 54e2b2202..803fd0a98 100644
--- a/applet.h
+++ b/applet.h
@@ -1003,9 +1003,15 @@ class PLASMA_EXPORT Applet : public QGraphicsWidget
         void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons);
 
         /**
-         * Called when any of the geometry constraints have been updated.
+         * Called when any of the constraints for the applet have been updated. These constraints
+         * range from notifying when the applet has officially "started up" to when geometry changes
+         * to when the form factor changes.
          *
-         * This is always called prior to painting and should be used as an
+         * Each constraint that has been changed is passed in the constraints flag.
+         * All of the constraints and how they work is documented in the @see Plasma::Constraints
+         * enumeration.
+         *
+         * On applet creation, this is always called prior to painting and can be used as an
          * opportunity to layout the widget, calculate sizings, etc.
          *
          * Do not call update() from this method; an update() will be triggered
diff --git a/plasma.h b/plasma.h
index e4a1c7b1f..9d4a26526 100644
--- a/plasma.h
+++ b/plasma.h
@@ -42,23 +42,15 @@ namespace Plasma
  * for instance in Applet::constraintsUpdated
  */
 enum Constraint {
-    NoConstraint = 0,
-    /** The FormFactor for an object */
-    FormFactorConstraint = 1,
-    /** The Location of an object */
-    LocationConstraint = 2,
-    /** Which screen an object is on */
-    ScreenConstraint = 4,
-    /** the size of the applet was changed */
-    SizeConstraint = 8,
-    /** the immutability (locked) nature of the applet changed  */
-    ImmutableConstraint = 16,
-    /** application startup has completed */
-    StartupCompletedConstraint = 32,
-    /** the desktop context has changed */
-    ContextConstraint = 64,
-    /** the position of the popup needs to be recalculated*/
-    PopupConstraint = 128,
+    NoConstraint = 0, /**< No constraint; never passed in to Applet::constraintsEvent on its own */
+    FormFactorConstraint = 1, /**< The FormFactor for an object */
+    LocationConstraint = 2, /**< The Location of an object */
+    ScreenConstraint = 4, /**< Which screen an object is on */
+    SizeConstraint = 8, /**< the size of the applet was changed */
+    ImmutableConstraint = 16, /**< the immutability (locked) nature of the applet changed  */
+    StartupCompletedConstraint = 32, /**< application startup has completed */
+    ContextConstraint = 64, /**< the context (e.g. activity) has changed */
+    PopupConstraint = 128, /**< the position of the popup needs to be recalculated*/
     AllConstraints = FormFactorConstraint | LocationConstraint | ScreenConstraint |
     SizeConstraint | ImmutableConstraint | ContextConstraint | PopupConstraint
 };