From 6d6b071b92dd5879754f1b92abc276416507e27a Mon Sep 17 00:00:00 2001
From: "bzbarsky%mit.edu"
 <bzbarsky%mit.edu@18797224-902f-48f8-a5cc-f745e15eee43>
Date: Tue, 22 Nov 2005 15:49:44 +0000
Subject: [PATCH] Fix some comments.  Bug 303817, r+sr=jst

git-svn-id: svn://10.0.0.236/trunk@185133 18797224-902f-48f8-a5cc-f745e15eee43
---
 mozilla/content/base/public/nsIDocument.h | 31 ++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/mozilla/content/base/public/nsIDocument.h b/mozilla/content/base/public/nsIDocument.h
index fa010e5d920..888f735cd08 100644
--- a/mozilla/content/base/public/nsIDocument.h
+++ b/mozilla/content/base/public/nsIDocument.h
@@ -108,7 +108,8 @@ class nsIDOMUserDataHandler;
 
 //----------------------------------------------------------------------
 
-// Document interface
+// Document interface.  This is implemented by all document objects in
+// Gecko.
 class nsIDocument : public nsISupports
 {
 public:
@@ -123,6 +124,30 @@ public:
   {
   }
 
+  /**
+   * Let the document know that we're starting to load data into it.
+   * @param aCommand The parser command
+   *                 XXXbz It's odd to have that here.
+   * @param aChannel The channel the data will come from
+   * @param aLoadGroup The loadgroup this document should use from now on.
+   *                   Note that the document might not be the only thing using
+   *                   this loadgroup.
+   * @param aContainer The container this document is in.  This may be null.
+   *                   XXXbz maybe we should make it more explicit (eg make the
+   *                   container an nsIWebNavigation or nsIDocShell or
+   *                   something)?
+   * @param [out] aDocListener the listener to pump data from the channel into.
+   *                           Generally this will be the parser this document
+   *                           sets up, or some sort of data-handler for media
+   *                           documents.
+   * @param aReset whether the document should call Reset() on itself.  If this
+   *               is false, the document will NOT set its principal to the
+   *               channel's owner, will not clear any event listeners that are
+   *               already set on it, etc.
+   * @param aSink The content sink to use for the data.  If this is null and
+   *              the document needs a content sink, it will create one based
+   *              on whatever it knows about the data it's going to load.
+   */  
   virtual nsresult StartDocumentLoad(const char* aCommand,
                                      nsIChannel* aChannel,
                                      nsILoadGroup* aLoadGroup,
@@ -130,11 +155,11 @@ public:
                                      nsIStreamListener **aDocListener,
                                      PRBool aReset,
                                      nsIContentSink* aSink = nsnull) = 0;
-
   virtual void StopDocumentLoad() = 0;
 
   /**
-   * Return the title of the document. May return null.
+   * Return the title of the document.  This will return a void string
+   * if there is no title for this document).
    */
   const nsString& GetDocumentTitle() const
   {