3 files changed, 83 insertions, 21 deletions
diff --git a/doc/src/examples/hapticsquare.qdoc b/doc/src/examples/hapticsquare.qdoc
index f3ca4ea55c..8fc55b4a53 100644
--- a/doc/src/examples/hapticsquare.qdoc
+++ b/doc/src/examples/hapticsquare.qdoc
@@ -83,8 +83,7 @@
 
     \list
         \o \c {HapticButton}: Implementation of a button. It
-            inherits QWidget and sends signals for button clicks. It can
-            also be a toggle button.
+            inherits QWidget and sends signals for button clicks.
         \o \c {Dialog}: A QDialog subclass that displays the four
             \c{HapticButton}s mentioned above,
             connects them to its slots, and implements the functionality to
@@ -126,8 +125,7 @@
     \snippet examples/hapticsquare/hapticsquare.cpp 1
 
     The \c m_ocean is a periodic effect, i.e., it repeats after
-    \l{QFeedbackHapticsEffect::}{period()} milliseconds. To stop a periodic
-    effect, you must call \l{QFeedbackEffect::}{stop()}.  Note that the
+    \l{QFeedbackHapticsEffect::}{period()} milliseconds.  Note that the
     \l{QFeedbackHapticsEffect::}{duration()} must be greater than the period
     in order for the periodicity of the effect to be discernable.
 
@@ -164,6 +162,8 @@
     simple example which illustrates some simple uses of the API.
     Also, the example will not work correctly on platforms which do not have a
     QFeedbackHapticInterface (haptic effect provider) plugin loaded.  On such
-    platforms, clicking the buttons will have no effect.
+    platforms, clicking the buttons will have no effect.  On Maemo5, periodic
+    effects do not support attack or fade, and so the ocean effect is not
+    smooth.
 */
 
diff --git a/doc/src/feedback.qdoc b/doc/src/feedback.qdoc
index 95024f0fac..6c7335695b 100644
--- a/doc/src/feedback.qdoc
+++ b/doc/src/feedback.qdoc
@@ -34,12 +34,12 @@
 
 \ingroup mobility
 
-The Feedback API enables a client to provide feedback (both tactile and audio) to the
-user in response to their actions (for example, touching an onscreen button), and to
-control the vibration of the device (when a vibrator is used) or the piezo feedback
-from the screen.
+The Feedback API enables a client to control and provide tactile and audio feedback
+to the user. The feedback is in response to user actions. For example, touching an
+onscreen button. Control of the feedback involves control of the vibration of
+the device, when a vibrator is used, or the piezo feedback from the screen.
 
-This is part of the Qt Mobility Project.
+This is part of the QtMobility Project.
 
 \tableofcontents
 
@@ -76,7 +76,7 @@ check what formats are supported by the system by calling QFeedbackFileEffect::s
 For the vast majority of use cases, the QFeedbackEffect, QFeedbackHapticsEffect
 and QFeedbackFileEffect classes are the only classes which developers will use
 in their programs.  There are some special cases, however, where they may wish
-to implement their own feedback plugin.  The Qt Mobility Feedback API allows
+to implement their own feedback plugin.  The QtMobility Feedback API allows
 third party developers to implement QFeedbackInterface in a plugin which may be
 loaded by the plugin loading mechanism to play feedback effects.
 
@@ -93,15 +93,21 @@ by a plugin to provide effects to clients are:
 
 Generally, the device platform will provide an implementation of each of the
 three different interfaces, which will be the default plugins used for the
-various QFeedbackEffects.
+various \l {QFeedbackEffect}s.
 
-\section1 Usage
+\section2 Platform Issues
 
-\note On Symbian vibration feature needs to be enabled in user profile for the API to work.
+\note On Symbian, vibration feature needs to be enabled in the user profile for the API to work.
+
+\note On Maemo5, periodic vibration does not support attack or fade.
+
+\section1 Using Effects
+
+\section2 Theme Effects
 
 The most common use of the API is to play system theme effects for user
-interface interaction notifications (e.g., button clicks, etc).  These types
-of system theme effects can be played instantaneously, but cannot be paused or
+interface interaction notifications, for example, button clicks.  These
+system theme effects can be played instantaneously, but cannot be paused or
 stopped.  They are played via the static QFeedbackEffect::playThemeEffect()
 function:
 \snippet ../../doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Play the system theme button click effect
@@ -111,13 +117,69 @@ interactions and notifications, to allow an application to maintain greater
 consistency with the platform user experience.
 \snippet ../../doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Play the system theme bounce effect
 
+\section2 Custom Effects
+
 The next most common use of the API is to define a custom effect which can be
 used to notify the user of application-specific events or to increase the
-immersiveness of an application.  A custom haptic effect may be defined in the
-following manner:
+immersiveness of an application.  A custom effect may be either periodic or
+non-periodic.
+
+The following diagram shows the graph of intensity over time of a non-periodic
+effect which was started at time \c t and ended at time \c q, with an
+\l{QFeedbackHapticsEffect::intensity()}{intensity} of \c{I}, an
+\l{QFeedbackHapticsEffect::attackIntensity()}{attack intensity} of \c{AI}, a
+\l{QFeedbackHapticsEffect::fadeIntensity()}{fade intensity} of \c{FI}, an
+\l{QFeedbackHapticsEffect::attackTime()}{attack time} of \c{AT}, and a
+\l{QFeedbackHapticsEffect::fadeTime()}{fade time} of \c{FT}, with a total
+\l{QFeedbackEffect::duration()}{duration} of \c{Duration} milliseconds:
+\code
+   Intensity
+        ^
+      I_|
+        |        .--------------.
+        |       /                \
+     AI_|      /                  \
+        |     (                    \
+        |     |                     \
+     FI_|     |                      )
+        |     |                      |
+        |     |                      |
+        +-----t----------------------q----->  Time (msec)
+              <AT>              <-FT->
+              <-------Duration------->
+\endcode
+
+The following diagram shows the graph of intensity over time of a periodic
+effect which was started at time \c t and ended at time \c q, with an
+\l{QFeedbackHapticsEffect::intensity()}{intensity} of \c{I}, an
+\l{QFeedbackHapticsEffect::attackIntensity()}{attack intensity} of \c{AI}, a
+\l{QFeedbackHapticsEffect::fadeIntensity()}{fade intensity} of \c{FI}, an
+\l{QFeedbackHapticsEffect::attackTime()}{attack time} of \c{AT}, and a
+\l{QFeedbackHapticsEffect::fadeTime()}{fade time} of \c{FT}, with a
+\l{QFeedbackHapticsEffect::period()}{period} of \c{Period} milliseconds and a total
+\l{QFeedbackEffect::duration()}{duration} of \c{Duration} milliseconds:
+\code
+   Intensity
+        ^
+      I_|
+        |        .-------.        .-------.        .-----+
+        |       /         \      /         \      /      |
+     AI_|      /           \    /           \    /       |
+        |     (             \  (             \  (        |
+        |     |              \ |              \ |        |
+     FI_|     |               \|               \|        |
+        |     |                '                '        |
+        |     |                                          |
+        +-----t------------------------------------------q----->  Time (msec)
+              <AT>       <-FT->
+              <-----Period---->
+              <------------------Duration---------------->
+\endcode
+
+A custom haptic effect may be defined in the following manner:
 \snippet ../../doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Define a custom haptic effect
-Note that no periodicity was defined for the effect, although that can be done
-by calling QFeedbackHapticEffect::setPeriod() if required.
+\note No periodicity was defined for the effect, although that can be done
+by calling QFeedbackHapticsEffect::setPeriod() if required.
 
 Once the effect has been defined, it may be played via the API offered in the
 QFeedbackEffect base class:
diff --git a/doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp b/doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp
index eab5d1b4cf..082ec2c1f6 100644
--- a/doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp
+++ b/doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp
@@ -64,7 +64,7 @@ void completeExample()
     rumble.setAttackIntensity(0.0);
     rumble.setAttackTime(250);
     rumble.setIntensity(1.0);
-    rumble.setDuration(100);
+    rumble.setDuration(1000);
     rumble.setFadeTime(250);
     rumble.setFadeIntensity(0.0);
 //! [Define a custom haptic effect]