Make documentation a little more explicit about the ownership model. Bug

283108, r=biesi, sr=darin

embedding/browser/webBrowser/nsIWebBrowser.idl

@@ -148,11 +148,13 @@ interface nsIWebBrowser : nsISupports
      * their own implementation if they intend to override or prevent
      * how certain kinds of content are loaded.
      *
-     * @note The implementation should not refcount this interface; it
+     * @note If this attribute is set to an object that implements
-     *       should assume that a non nsnull value is always valid.
+     *       nsISupportsWeakReference, the implementation should get the
-     *       The embedder should explicitly set this value back to nsnull
+     *       nsIWeakReference and hold that.  Otherwise, the implementation
-     *       if the parent content listener is destroyed before the
+     *       should not refcount this interface; it should assume that a non
-     *       browser object.
+     *       null value is always valid.  In that case, the embedder should
+     *       explicitly set this value back to null if the parent content
+     *       listener is destroyed before the browser object.
      *
      * @see nsIURIContentListener
      */

uriloader/base/nsIURIContentListener.idl

@@ -153,6 +153,14 @@ interface nsIURIContentListener : nsISupports
  /**
   * The parent content listener if this particular listener is part of a chain
   * of content listeners (i.e. a docshell!)
+  *
+  * @note If this attribute is set to an object that implements
+  *       nsISupportsWeakReference, the implementation should get the
+  *       nsIWeakReference and hold that.  Otherwise, the implementation
+  *       should not refcount this interface; it should assume that a non
+  *       null value is always valid.  In that case, the caller is
+  *       responsible for explicitly setting this value back to null if the
+  *       parent content listener is destroyed.
   */
   attribute nsIURIContentListener parentContentListener;
 };