diff --git a/extender.h b/extender.h
index ef0e207cc..044237b38 100644
--- a/extender.h
+++ b/extender.h
@@ -48,6 +48,17 @@ class Applet;
  *
  * If you wish to have a different presentation of extender items, you can choose to subclass
  * Extender and reimplement the extenderItem* events and, optionally, the saveState function.
+ *
+ * To use an Extender in you applet, you'll have to instantiate one. A call to extender() in your
+ * applet will create an extender on your applet if you haven't got one already. Every applet can
+ * contain only one extender. Think of it as a decorator that adds some functionality to applets
+ * that require it. Never instantiate an Extender before init() in your applet. This won't work
+ * correctly since a scene is required when an Extender is instantiated.
+ *
+ * As soon as an Extender is instantiated, ExtenderItems contained previously in this Extender are
+ * restored using the initExtenderItem function from the applet the items originally came from. For
+ * more information on how this works and how to use ExtenderItems in general, see the ExtenderItem
+ * API documentation.
  */
 class PLASMA_EXPORT Extender : public QGraphicsWidget
 {
@@ -59,27 +70,29 @@ class PLASMA_EXPORT Extender : public QGraphicsWidget
          * Description on how to render the extender's items.
          */
         enum Appearance {
-            NoBorders = 0,  /** Draws no borders on the extender's items. When placed in an applet
-                                on the desktop, use this setting and use the standard margins of
-                                the applet containing this extender. */
-            BottomUpStacked = 1, /** Draws no borders on the topmost extenderitem, but draws the
-                                     left, top and right border on subsequent items. When margins
-                                     of the containing dialog are set to 0, except for the top
-                                     margin, this leads to the 'stacked' look, recommended for
-                                     extenders of applet's contained in a panel at the bottom of
-                                     the screen. */
-            TopDownStacked = 2 /** Draws no borders on the bottom extenderitem, but draws the
-                                   left, bottom and right border on subsequent items. When margins
-                                   of the containing dialog are set to 0, except for the bottom
-                                   margin, this leads to the 'stacked' look, recommended for
-                                   extenders of applet's contained in a panel at the top of
-                                   the screen. */
+            NoBorders = 0,  /**< Draws no borders on the extender's items. When placed in an applet
+                                 on the desktop, use this setting and use the standard margins of
+                                 the applet containing this extender. */
+            BottomUpStacked = 1, /**< Draws no borders on the topmost extenderitem, but draws the
+                                      left, top and right border on subsequent items. When margins
+                                      of the containing dialog are set to 0, except for the top
+                                      margin, this leads to the 'stacked' look, recommended for
+                                      extenders of applet's contained in a panel at the bottom of
+                                      the screen. */
+            TopDownStacked = 2 /**< Draws no borders on the bottom extenderitem, but draws the
+                                    left, bottom and right border on subsequent items. When margins
+                                    of the containing dialog are set to 0, except for the bottom
+                                    margin, this leads to the 'stacked' look, recommended for
+                                    extenders of applet's contained in a panel at the top of
+                                    the screen. */
         };
 
         /**
          * Creates an extender. Note that extender expects applet to have a config(), and needs a
          * scene because of that. So you should only instantiate an extender in init() or later, not
          * in an applet's constructor.
+         * The constructor also takes care of restoring ExtenderItems that were contained in this
+         * extender before, so ExtenderItems are persistent between sessions.
          * @param applet The applet this extender is part of. Null is not allowed here.
          */
         explicit Extender(Applet *applet);
@@ -87,7 +100,7 @@ class PLASMA_EXPORT Extender : public QGraphicsWidget
         ~Extender();
 
         /**
-         * @param emptyExtenderMessage The text to be shown whenever the applet's extender is empty.
+         * @param message The text to be shown whenever the applet's extender is empty.
          * Defaults to i18n'ed "no items".
          */
         void setEmptyExtenderMessage(const QString &message);
@@ -194,12 +207,12 @@ class PLASMA_EXPORT Extender : public QGraphicsWidget
         virtual PanelSvg::EnabledBorders enabledBordersForItem(ExtenderItem *item) const;
 
         /**
-         * @reimplemented from QGraphicsWidget
+         * Reimplemented from QGraphicsWidget
          */
         QVariant itemChange(GraphicsItemChange change, const QVariant &value);
 
         /**
-         * @reimplemented from QGraphicsWidget
+         * Reimplemented from QGraphicsWidget
          */
         void resizeEvent(QGraphicsSceneResizeEvent *event);
 
diff --git a/extenderitem.h b/extenderitem.h
index 712ddb40e..4b7ecfae6 100644
--- a/extenderitem.h
+++ b/extenderitem.h
@@ -42,6 +42,34 @@ class ExtenderItemPrivate;
  * This class wraps around a QGraphicsWidget and provides drag&drop handling, a draghandle,
  * title and ability to display qactions as a row of icon, ability to expand, collapse, return
  * to source and tracks configuration associated with this item for you.
+ *
+ * Typical usage of ExtenderItems in your applet could look something like this:
+ *
+ * @code
+ * ExtenderItem *item = new ExtenderItem(extender());
+ * //name can be used to later access this item through extender()->item(name):
+ * item->setName("networkmonitoreth0");
+ * item->config().writeEntry("device", "eth0");
+ * initExtenderItem(item);
+ * @endcode
+ *
+ * You'll then need to implement the initExtenderItem function. Having this function in your applet
+ * makes sure that detached extender items get restored after plasma is restarted, just like applets
+ * are. That is also the reason that we write an entry in item->config().
+ * In this function you should instantiate a QGraphicsWidget or QGraphicsItem and call the
+ * setWidget function on the ExtenderItem. This is the only correct way of adding actual content to
+ * a extenderItem. An example:
+ *
+ * @code
+ * void MyApplet::initExtenderItem(Plasma::ExtenderItem *item)
+ * {
+ *     QGraphicsWidget *myNetworkMonitorWidget = new NetworkMonitorWidget(item);
+ *     dataEngine("networktraffic")->connectSource(item->config().readEntry("device", ""),
+ *                                                 myNetworkMonitorWidget);
+ *     item->setWidget(myNetworkMonitorWidget);
+ * }
+ * @endcode
+ *
  */
 class PLASMA_EXPORT ExtenderItem : public QGraphicsWidget
 {
@@ -59,8 +87,6 @@ class PLASMA_EXPORT ExtenderItem : public QGraphicsWidget
         /**
          * The constructor takes care of adding this item to an extender.
          * @param hostExtender The extender where the extender item belongs to.
-         * TODO: extenderItemId might not be necesarry in the constructor if I rewrite some
-         * stuff.
          * @param extenderItemId the id of the extender item. Use the default 0 to assign a new,
          * unique id to this extender item.
          */