diff --git a/svg.h b/svg.h
index 9ec92f690..3ed3fa76f 100644
--- a/svg.h
+++ b/svg.h
@@ -360,7 +360,22 @@ class PLASMA_EXPORT Svg : public QObject
         Theme *theme() const;
 
     Q_SIGNALS:
+        /**
+         * Emitted whenever the SVG data has changed in such a way that a repaint is required.
+         * Any usage of an Svg object that does the painting itself must connect to this signal
+         * and respond by updating the painting. Note that connected to Theme::themeChanged is
+         * incorrect in such a use case as the Svg itself may not be updated yet nor may theme
+         * change be the only case when a repaint is needed. Also note that classes or QML code
+         * which take Svg objects as parameters for their own painting all respond to this signal
+         * so that in those cases manually responding to the signal is unnecessary; ONLY when
+         * direct, manual painting with an Svg object is done in application code is this signal
+         * used.
+         */
         void repaintNeeded();
+
+        /**
+         * Emitted whenever the size of the Svg is changed. @see resize()
+         */
         void sizeChanged();
 
     private:
diff --git a/theme.h b/theme.h
index 2d0291196..29c81df98 100644
--- a/theme.h
+++ b/theme.h
@@ -386,8 +386,12 @@ class PLASMA_EXPORT Theme : public QObject
 
     Q_SIGNALS:
         /**
-         * Emitted when the user changes the theme. SVGs should be reloaded at
-         * that point
+         * Emitted when the user changes the theme. Stylesheet usage, colors, etc. should
+         * be updated at this point. However, SVGs should *not* be repainted in response
+         * to this signal; connect to Svg::repaintNeeded() instead for that, as Svg objects
+         * need repainting not only when themeChanged() is emitted; moreover Svg objects
+         * connect to and respond appropriately to themeChanged() internally, emitting 
+         * Svg::repaintNeeded() at an appropriate time.
          */
         void themeChanged();