282103 - better document the dynamic overlay load method, and announce that it will change for 2.0 r=bryner a=cbeard

dom/public/idl/xul/nsIDOMXULDocument.idl

@@ -66,5 +66,22 @@ interface nsIDOMXULDocument : nsISupports
 
   void                      persist(in DOMString id, in DOMString attr);
 
+  /**
+   * Loads a XUL overlay and merges it with the current document, notifying an
+   * observer when the merge is complete. 
+   * @param   url
+   *          The URL of the overlay to load and merge
+   * @param   observer
+   *          An object implementing nsIObserver that will be notified with a
+   *          message of topic "xul-overlay-merged" when the merge is complete. 
+   *          The subject parameter of |observe| will QI to a nsIURI - the URI 
+   *          of the merged overlay. 
+   *
+   * NOTICE:  In the 2.0 timeframe this API will change such that the 
+   *          implementation will fire a DOMXULOverlayMerged event upon merge
+   *          completion rather than notifying an observer. Do not rely on this
+   *          API's behavior _not_ to change because it will!
+   *          - Ben Goodger (8/23/2005)
+   */
   void                      loadOverlay(in DOMString url, in nsIObserver aObserver);
 };