diff --git a/lib/kwineffects.h b/lib/kwineffects.h
index 5706b155d1..3871591666 100644
--- a/lib/kwineffects.h
+++ b/lib/kwineffects.h
@@ -38,22 +38,12 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 #include <assert.h>
 
-/** @addtogroup kwineffects */
-/** @{ */
-
-#define KWIN_EFFECT_API_MAKE_VERSION( major, minor ) (( major ) << 8 | ( minor )) 
-#define KWIN_EFFECT_API_VERSION_MAJOR 0
-#define KWIN_EFFECT_API_VERSION_MINOR 6
-#define KWIN_EFFECT_API_VERSION KWIN_EFFECT_API_MAKE_VERSION( \
-    KWIN_EFFECT_API_VERSION_MAJOR, KWIN_EFFECT_API_VERSION_MINOR )
 
 class KLibrary;
 class KConfigGroup;
 class KActionCollection;
 class QKeyEvent;
 
-/** @defgroup kwineffects KWin effects library */
-
 namespace KWin
 {
 
@@ -75,6 +65,105 @@ typedef QPair< Effect*, Window > InputWindowPair;
 typedef QList< EffectWindow* > EffectWindowList;
 
 
+/** @defgroup kwineffects KWin effects library
+ * KWin effects library contains necessary classes for creating new KWin
+ * compositing effects.
+ *
+ * @section creating Creating new effects
+ * This example will demonstrate the basics of creating an effect. We'll use
+ *  CoolEffect as the class name, cooleffect as internal name and
+ *  "Cool Effect" as user-visible name of the effect.
+ *
+ * This example doesn't demonstrate how to write the effect's code. For that,
+ *  see the documentation of the Effect class.
+ *
+ * @subsection creating-class CoolEffect class
+ * First you need to create CoolEffect class which has to be a subclass of
+ *  @ref KWin::Effect. In that class you can reimplement various virtual
+ *  methods to control how and where the windows are drawn.
+ *
+ * @subsection creating-macro KWIN_EFFECT macro
+ * To make KWin aware of your new effect, you first need to use the
+ *  @ref KWIN_EFFECT macro to connect your effect's class to it's internal
+ *  name. The internal name is used by KWin to identify your effect. It can be
+ *  freely chosen (although it must be a single word), must be unique and won't
+ * be shown to the user. For our example, you would use the macro like this:
+ * @code
+ * KWIN_EFFECT(cooleffect, CoolEffect)
+ * @endcode
+ *
+ * @subsection creating-buildsystem Buildsystem
+ * To build the effect, you can use the KWIN_ADD_EFFECT() cmake macro which
+ *  can be found in effects/CMakeLists.txt file in KWin's source. First
+ *  argument of the macro is the name of the library that will contain
+ *  your effect. Although not strictly required, it is usually a good idea to
+ *  use the same name as your effect's internal name there. Following arguments
+ *  to the macro are the files containing your effect's source. If our effect's
+ *  source is in cooleffect.cpp, we'd use following:
+ * @code
+ *  KWIN_ADD_EFFECT(cooleffect cooleffect.cpp)
+ * @endcode
+ *
+ * This macro takes care of compiling your effect. You'll also need to install
+ *  your effect's .desktop file, so the example CMakeLists.txt file would be
+ *  as follows:
+ * @code
+ *  KWIN_ADD_EFFECT(cooleffect cooleffect.cpp)
+ *  install( FILES cooleffect.desktop DESTINATION ${SERVICES_INSTALL_DIR}/kwin )
+ * @endcode
+ *
+ * @subsection creating-desktop Effect's .desktop file
+ * You will also need to create .desktop file to set name, description, icon
+ *  and other properties of your effect. Important fields of the .desktop file
+ *  are:
+ *  @li Name User-visible name of your effect
+ *  @li Icon Name of the icon of the effect
+ *  @li Comment Short description of the effect
+ *  @li Type must be "Service"
+ *  @li X-KDE-ServiceTypes must be "KWin/Effect"
+ *  @li X-KDE-PluginInfo-Name effect's internal name as passed to the KWIN_EFFECT macro plus "kwin4_effect_" prefix
+ *  @li X-KDE-PluginInfo-Category effect's category. Should be one of Appearance, Accessibility, Window Management, Demos, Tests, Misc
+ *  @li X-KDE-PluginInfo-EnabledByDefault whether the effect should be enabled by default (use sparingly). Default is false
+ *  @li X-KDE-Library name of the library containing the effect. This is the first argument passed to the KWIN_ADD_EFFECT macro in cmake file plus "kwin4_effect_" prefix.
+ *
+ * Example cooleffect.desktop file follows:
+ * @code
+[Desktop Entry]
+Name=Cool Effect
+Comment=The coolest effect you've ever seen
+Icon=preferences-system-windows-effect-cooleffect
+
+Type=Service
+X-KDE-ServiceTypes=KWin/Effect
+X-KDE-PluginInfo-Author=My Name
+X-KDE-PluginInfo-Email=my@email.here
+X-KDE-PluginInfo-Name=kwin4_effect_cooleffect
+X-KDE-PluginInfo-Category=Misc
+X-KDE-Library=kwin4_effect_cooleffect
+ * @endcode
+ *
+ *
+ * @section accessing Accessing windows and workspace
+ * Effects can gain access to the properties of windows and workspace via
+ *  EffectWindow and EffectsHandler classes.
+ *
+ * There is one global EffectsHandler object which you can access using the
+ *  @ref effects pointer.
+ * For each window, there is an EffectWindow object which can be used to read
+ *  window properties such as position and also to change them.
+ *
+ * For more information about this, see the documentation of the corresponding
+ *  classes.
+ *
+ * @{
+ **/
+
+#define KWIN_EFFECT_API_MAKE_VERSION( major, minor ) (( major ) << 8 | ( minor ))
+#define KWIN_EFFECT_API_VERSION_MAJOR 0
+#define KWIN_EFFECT_API_VERSION_MINOR 6
+#define KWIN_EFFECT_API_VERSION KWIN_EFFECT_API_MAKE_VERSION( \
+    KWIN_EFFECT_API_VERSION_MAJOR, KWIN_EFFECT_API_VERSION_MINOR )
+
 /**
  * @short Base class for all KWin effects
  *