Bug 415941 – nsISessionStore documentation: clarify the meaning of "window". r=mano

browser/components/sessionstore/nsISessionStore.idl

@@ -43,7 +43,23 @@ interface nsIDOMNode;
 /**
  * nsISessionStore keeps track of the current browsing state - i.e.
  * tab history, cookies, scroll state, form data, POSTDATA and window features
- * - and allows to restore everything into one window.
+ * - and allows to restore everything into one browser window.
+ *
+ * The nsISessionStore API operates mostly on browser windows and the tabbrowser
+ * tabs contained in them:
+ *
+ * * "Browser windows" are those DOM windows having loaded
+ * chrome://browser/content/browser.xul . From overlays you can just pass the
+ * global |window| object to the API, though (or |top| from a sidebar).
+ * From elsewhere you can get browser windows through the nsIWindowMediator
+ * by looking for "navigator:browser" windows.
+ *
+ * * "Tabbrowser tabs" are all the child nodes of a browser window's
+ * |getBrowser().tabContainer| such as e.g. |getBrowser().selectedTab|.
+ *
+ * Note: This API will break in all sorts of way if the preference
+ *       browser.sessionstore.enabled is set to false (once bug ...
+ *       is fixed, the service won't be available at all).
  */
 
 [scriptable, uuid(58d17e12-a80f-11dc-8314-0800200c9a66)]
@@ -56,7 +72,7 @@ interface nsISessionStore : nsISupports
 
   /**
    * Get the current browsing state.
-   * @return a JSON string representing the session state.
+   * @returns a JSON string representing the session state.
    */
   AString getBrowserState();
 
@@ -70,29 +86,29 @@ interface nsISessionStore : nsISupports
   void setBrowserState(in AString aState);
 
   /**
-   * @param aWindow is the window whose state is to be returned.
+   * @param aWindow is the browser window whose state is to be returned.
    * 
-   * @return a JSON string representing a session state with only one window.
+   * @returns a JSON string representing a session state with only one window.
    */
   AString getWindowState(in nsIDOMWindow aWindow);
 
   /**
-   * @param aWindow    is the window whose state is to be set.
+   * @param aWindow    is the browser window whose state is to be set.
    * @param aState     is a JSON string representing a session state.
    * @param aOverwrite boolean overwrite existing tabs
    */
   void setWindowState(in nsIDOMWindow aWindow, in AString aState, in boolean aOverwrite);
 
   /**
-   * @param aTab is the tab whose state is to be returned.
+   * @param aTab is the tabbrowser tab whose state is to be returned.
    * 
-   * @return a JSON string representing the state of the tab
+   * @returns a JSON string representing the state of the tab
    *         (note: doesn't contain cookies - if you need them, use getWindowState instead).
    */
   AString getTabState(in nsIDOMNode aTab);
 
   /**
-   * @param aTab   is the tab whose state is to be set.
+   * @param aTab   is the tabbrowser tab whose state is to be set.
    * @param aState is a JSON string representing a session state.
    */
   void setTabState(in nsIDOMNode aTab, in AString aState);
@@ -100,28 +116,28 @@ interface nsISessionStore : nsISupports
   /**
    * Duplicates a given tab as thoroughly as possible.
    *
-   * @param aWindow is the window into which the tab will be duplicated.
-   * @param aTab    is the tab to duplicate (can be from a different window).
-   * @return a reference to the newly created tab.
+   * @param aWindow is the browser window into which the tab will be duplicated.
+   * @param aTab    is the tabbrowser tab to duplicate (can be from a different window).
+   * @returns a reference to the newly created tab.
    */
   nsIDOMNode duplicateTab(in nsIDOMWindow aWindow, in nsIDOMNode aTab);
 
   /**
-   * Get the number of restore-able tabs for a window
+   * Get the number of restore-able tabs for a browser window
    */
   unsigned long getClosedTabCount(in nsIDOMWindow aWindow);
 
   /**
    * Get closed tab data
-   * @return a JSON string representing the list of closed tabs.
+   *
+   * @param aWindow is the browser window for which to get closed tab data
+   * @returns a JSON string representing the list of closed tabs.
    */
   AString getClosedTabData(in nsIDOMWindow aWindow);
 
   /**
-   * @param aWindow
-   *          The window to reopen a closed tab in.
-   * @param aIndex
-   *          Indicates the window to be restored (FIFO ordered).
+   * @param aWindow is the browser window to reopen a closed tab in.
+   * @param aIndex  is the index of the tab to be restored (FIFO ordered).
    */
   void undoCloseTab(in nsIDOMWindow aWindow, in unsigned long aIndex);
 
@@ -129,46 +145,46 @@ interface nsISessionStore : nsISupports
    * @param aWindow is the window to get the value for.
    * @param aKey    is the value's name.
    * 
-   * @return A string value or "" if none is set.
+   * @returns A string value or an empty string if none is set.
    */
   AString getWindowValue(in nsIDOMWindow aWindow, in AString aKey);
 
   /**
-   * @param aWindow      is the window to set the value for.
+   * @param aWindow      is the browser window to set the value for.
    * @param aKey         is the value's name.
    * @param aStringValue is the value itself (use toSource/eval before setting JS objects).
    */
   void setWindowValue(in nsIDOMWindow aWindow, in AString aKey, in AString aStringValue);
   
   /**
-   * @param aWindow is the window to get the value for.
+   * @param aWindow is the browser window to get the value for.
    * @param aKey    is the value's name.
    */
   void deleteWindowValue(in nsIDOMWindow aWindow, in AString aKey);
 
   /**
-   * @param aTab is the tab to get the value for.
+   * @param aTab is the tabbrowser tab to get the value for.
    * @param aKey is the value's name.
    * 
-   * @return A string value or "" if none is set.
+   * @returns A string value or an empty string if none is set.
    */
   AString getTabValue(in nsIDOMNode aTab, in AString aKey);
 
   /**
-   * @param aTab         is the tab to set the value for.
+   * @param aTab         is the tabbrowser tab to set the value for.
    * @param aKey         is the value's name.
    * @param aStringValue is the value itself (use toSource/eval before setting JS objects).
    */
   void setTabValue(in nsIDOMNode aTab, in AString aKey, in AString aStringValue);
 
   /**
-   * @param aTab is the tab to get the value for.
+   * @param aTab is the tabbrowser tab to get the value for.
    * @param aKey is the value's name.
    */
   void deleteTabValue(in nsIDOMNode aTab, in AString aKey);
 
   /**
-   * @param aName is the name of the attribute to save/restore for all xul:tabs.
+   * @param aName is the name of the attribute to save/restore for all tabbrowser tabs.
    */
   void persistTabAttribute(in AString aName);
 };