diff --git a/mozilla/xpcom/ds/nsIObserver.idl b/mozilla/xpcom/ds/nsIObserver.idl
index 6034d2260f5..8b69ab99249 100644
--- a/mozilla/xpcom/ds/nsIObserver.idl
+++ b/mozilla/xpcom/ds/nsIObserver.idl
@@ -22,20 +22,27 @@
 
 #include "nsISupports.idl"
 
+/**
+ * This interface is implemented by an object that needs
+ * to observe an event corresponding to a change in a 
+ * topic for a subject.
+ */
+
 [scriptable, uuid(DB242E01-E4D9-11d2-9DDE-000064657374)]
 interface nsIObserver : nsISupports {
 
-	/*------------------------------- Observe ----------------------------------
-    | Called when aTopic changes for aSubject (presumably; it is actually      |
-    | called whenever anyone calls nsIObserverService::Notify for aTopic).     |
-    |                                                                          |
-    | Implement this in your class to handle the event appropriately.  If      |
-    | your observer objects can respond to multiple topics and/or subjects,    |
-    | then you will have to filter accordingly.                                |
-	--------------------------------------------------------------------------*/
+   /**
+    * Called if the topic changes for the subject. If you expect 
+    * multiple topics/subjects, the impl is responsible for filtering.
+    *
+    * @param aSubject - the event specific data that has changed.
+    * @param aTopic   - indicates the event that has changed.
+    * @param aData    - out of band data specific to the topic/
+    *                   subject event.
+    */
     void Observe( in nsISupports aSubject,
 				  in wstring     aTopic,
-				  in wstring     someData );
+				  in wstring     aData );
 
 };