--- a/gfx/src/nsITheme.h
+++ b/gfx/src/nsITheme.h
@@ -123,16 +123,21 @@ public:
   };
 
   /**
    * Returns what we know about the transparency of the widget.
    */
   virtual Transparency GetWidgetTransparency(nsIFrame* aFrame, uint8_t aWidgetType)
   { return eUnknownTransparency; }
 
+  /**
+   * Sets |*aShouldRepaint| to indicate whether an attribute or content state
+   * change should trigger a repaint.  Call with null |aAttribute| (and
+   * null |aOldValue|) for content state changes.
+   */
   NS_IMETHOD WidgetStateChanged(nsIFrame* aFrame, uint8_t aWidgetType, 
                                 nsIAtom* aAttribute, bool* aShouldRepaint,
                                 const nsAttrValue* aOldValue)=0;
 
   NS_IMETHOD ThemeChanged()=0;
 
   virtual bool WidgetAppearanceDependsOnWindowFocus(uint8_t aWidgetType)
   { return false; }