--- a/content/base/public/nsISelectionDisplay.idl
+++ b/content/base/public/nsISelectionDisplay.idl
@@ -17,23 +17,21 @@ interface nsISelectionDisplay : nsISuppo
    /*
    SetSelectionFlags used to set whether you want to see HRULES/IMAGES with border.
     also used to tell if the presshell is an editor right now. this should change
     
     @param aToggle -either DISPLAY_(TEXT,IMAGES,FRAMES,ALL)
                     This will tell the rendering engine to draw the different
                     selection types. 
 
-    @return NS_OK if successful.
    */
     void setSelectionFlags(in short toggle);
 
    /*
    GetSelectionFlags used to get whether you want to see HRULES/IMAGES with border.
     also used to tell if the presshell is an editor right now. this should change
    
     @param short *aReturn - This will be filled with DISPLAY_(TEXT,IMAGE,FRAMES,ALL) 
                             bit flags.
-    @return NS_OK if successful.
    */
     short getSelectionFlags();
 
 };

--- a/docshell/base/nsIWebPageDescriptor.idl
+++ b/docshell/base/nsIWebPageDescriptor.idl
@@ -13,18 +13,17 @@
 interface nsIWebPageDescriptor : nsISupports
 {
   const unsigned long DISPLAY_AS_SOURCE = 0x0001;
   const unsigned long DISPLAY_NORMAL    = 0x0002;
 
  /**
   * Tells the object to load the page specified by the page descriptor
   *
-  * @return NS_OK            - 
-  *         NS_ERROR_FAILURE - 
+  * @throws NS_ERROR_FAILURE - 
   */
   void loadPage(in nsISupports aPageDescriptor, in unsigned long aDisplayType);
 
 
  /**
   * Retrieves the page descriptor for the curent document.
   */
   readonly attribute nsISupports currentDescriptor;

--- a/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl
+++ b/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl
@@ -90,19 +90,18 @@ interface nsIWebBrowserPersist : nsICanc
    * Current state of the persister object.
    */
   readonly attribute unsigned long currentState;
 
   /**
    * Value indicating the success or failure of the persist
    * operation.
    *
-   * @return NS_OK Operation was successful or is still ongoing.
-   * @return NS_BINDING_ABORTED Operation cancelled.
-   * @return NS_ERROR_FAILURE Non-specific failure.
+   * @throws NS_BINDING_ABORTED Operation cancelled.
+   * @throws NS_ERROR_FAILURE Non-specific failure.
    */
   readonly attribute nsresult result;
 
   /**
    * Callback listener for progress notifications. The object that the
    * embbedder supplies may also implement nsIInterfaceRequestor and be
    * prepared to return nsIAuthPrompt or other interfaces that may be required
    * to download data.
@@ -136,18 +135,17 @@ interface nsIWebBrowserPersist : nsICanc
    *                   in situations in which no such context is available
    *                   (eg. the operation has no logical association with any
    *                   window or document)
    *
    * @see nsIFile
    * @see nsIURI
    * @see nsIInputStream
    *
-   * @return NS_OK Operation has been started.
-   * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
+   * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
    */
   void saveURI(in nsIURI aURI, in nsISupports aCacheKey,
       in nsIURI aReferrer, in nsIInputStream aPostData,
       in string aExtraHeaders, in nsISupports aFile,
       in nsILoadContext aPrivacyContext);
 
   /**
    * @param aIsPrivate Treat the save operation as private (ie. with
@@ -258,18 +256,17 @@ interface nsIWebBrowserPersist : nsICanc
    * @param aEncodingFlags     Flags to pass to the encoder.
    * @param aWrapColumn        For text documents, indicates the desired width to
    *                           wrap text at. Parameter is ignored if wrapping is not
    *                           specified by the encoding flags.
    *
    * @see nsIFile
    * @see nsIURI
    *
-   * @return NS_OK Operation has been started.
-   * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
+   * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
    */
   void saveDocument(in nsIDOMDocument aDocument,
      in nsISupports aFile, in nsISupports aDataPath,
      in string aOutputContentType, in unsigned long aEncodingFlags,
      in unsigned long aWrapColumn);
 
   /**
    * Cancels the current operation. The caller is responsible for cleaning up

--- a/image/public/imgICache.idl
+++ b/image/public/imgICache.idl
@@ -27,18 +27,17 @@ interface imgICache : nsISupports
    *               If FALSE, evict everything except chrome images.
    */
   void clearCache(in boolean chrome);
 
   /**
    * Evict images from the cache.
    *
    * @param uri The URI to remove.
-   * @return NS_OK if \a uri was removed from the cache.
-   *         NS_ERROR_NOT_AVAILABLE if \a uri was unable to be removed from the cache.
+   * @throws NS_ERROR_NOT_AVAILABLE if \a uri was unable to be removed from the cache.
    */
   void removeEntry(in nsIURI uri);
 
   /**
    * Find Properties
    * Used to get properties such as 'type' and 'content-disposition'
    * 'type' is a nsISupportsCString containing the images' mime type such as 'image/png'
    * 'content-disposition' will be a nsISupportsCString containing the header

--- a/modules/libpref/public/nsIPrefBranch.idl
+++ b/modules/libpref/public/nsIPrefBranch.idl
@@ -65,18 +65,17 @@ interface nsIPrefBranch : nsISupports
   boolean getBoolPref(in string aPrefName);
 
   /**
    * Called to set the state of an individual boolean preference.
    *
    * @param aPrefName The boolean preference to set the state of.
    * @param aValue    The boolean value to set the preference to.
    *
-   * @return NS_OK The value was successfully set.
-   * @return Other The value was not set or is the wrong type.
+   * @throws Error if setting failed or the value is the wrong type.
    *
    * @see getBoolPref
    */
   void setBoolPref(in string aPrefName, in boolean aValue);
 
   /**
    * Called to get the state of an individual floating-point preference.
    * "Floating point" preferences are really string preferences that
@@ -102,18 +101,17 @@ interface nsIPrefBranch : nsISupports
   string getCharPref(in string aPrefName);
 
   /**
    * Called to set the state of an individual string preference.
    *
    * @param aPrefName The string preference to set.
    * @param aValue    The string value to set the preference to.
    *
-   * @return NS_OK The value was successfully set.
-   * @return Other The value was not set or is the wrong type.
+   * @throws Error if setting failed or the value is the wrong type.
    *
    * @see getCharPref
    */
   void setCharPref(in string aPrefName, in string aValue);
 
   /**
    * Called to get the state of an individual integer preference.
    *
@@ -126,18 +124,17 @@ interface nsIPrefBranch : nsISupports
   long getIntPref(in string aPrefName);
 
   /**
    * Called to set the state of an individual integer preference.
    *
    * @param aPrefName The integer preference to set the value of.
    * @param aValue    The integer value to set the preference to.
    *
-   * @return NS_OK The value was successfully set.
-   * @return Other The value was not set or is the wrong type.
+   * @throws Error if setting failed or the value is the wrong type.
    *
    * @see getIntPref
    */
   void setIntPref(in string aPrefName, in long aValue);
 
   /**
    * Called to get the state of an individual complex preference. A complex
    * preference is a preference which represents an XPCOM object that can not
@@ -147,18 +144,17 @@ interface nsIPrefBranch : nsISupports
    * @param aType     The XPCOM interface that this complex preference
    *                  represents. Interfaces currently supported are:
    *                    - nsIFile
    *                    - nsISupportsString (UniChar)
    *                    - nsIPrefLocalizedString (Localized UniChar)
    * @param aValue    The XPCOM object into which to the complex preference 
    *                  value should be retrieved.
    *
-   * @return NS_OK The value was successfully retrieved.
-   * @return Other The value does not exist or is the wrong type.
+   * @throws Error The value does not exist or is the wrong type.
    *
    * @see setComplexValue
    */
   void getComplexValue(in string aPrefName, in nsIIDRef aType,
                        [iid_is(aType), retval] out nsQIResult aValue);
 
   /**
    * Called to set the state of an individual complex preference. A complex
@@ -169,50 +165,46 @@ interface nsIPrefBranch : nsISupports
    * @param aType     The XPCOM interface that this complex preference
    *                  represents. Interfaces currently supported are:
    *                    - nsIFile
    *                    - nsISupportsString (UniChar)
    *                    - nsIPrefLocalizedString (Localized UniChar)
    * @param aValue    The XPCOM object from which to set the complex preference 
    *                  value.
    *
-   * @return NS_OK The value was successfully set.
-   * @return Other The value was not set or is the wrong type.
+   * @throws Error if setting failed or the value is the wrong type.
    *
    * @see getComplexValue
    */
   void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
 
   /**
    * Called to clear a user set value from a specific preference. This will, in
    * effect, reset the value to the default value. If no default value exists
    * the preference will cease to exist.
    *
    * @param aPrefName The preference to be cleared.
    *
    * @note
    * This method does nothing if this object is a default branch.
-   *
-   * @return NS_OK The user preference was successfully cleared.
    */
   void clearUserPref(in string aPrefName);
 
   /**
    * Called to lock a specific preference. Locking a preference will cause the
    * preference service to always return the default value regardless of
    * whether there is a user set value or not.
    *
    * @param aPrefName The preference to be locked.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the default branch.
    *
-   * @return NS_OK The preference was successfully locked.
-   * @return Other The preference does not exist or an error occurred.
+   * @throws Error The preference does not exist or an error occurred.
    *
    * @see unlockPref
    */
   void lockPref(in string aPrefName);
 
   /**
    * Called to check if a specific preference has a user value associated to
    * it.
@@ -259,18 +251,17 @@ interface nsIPrefBranch : nsISupports
    * value of the preference.
    *
    * @param aPrefName The preference to be unlocked.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the default branch.
    *
-   * @return NS_OK The preference was successfully unlocked.
-   * @return Other The preference does not exist or an error occurred.
+   * @throws Error The preference does not exist or an error occurred.
    *
    * @see lockPref
    */
   void    unlockPref(in string aPrefName);
 
 
   /**
    * Called to remove all of the preferences referenced by this branch.
@@ -278,18 +269,17 @@ interface nsIPrefBranch : nsISupports
    * @param aStartingAt The point on the branch at which to start the deleting
    *                    preferences. Pass in "" to remove all preferences
    *                    referenced by this branch.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on both.
    *
-   * @return NS_OK The preference(s) were successfully removed.
-   * @return Other The preference(s) do not exist or an error occurred.
+   * @throws Error The preference(s) do not exist or an error occurred.
    */
   void deleteBranch(in string aStartingAt);
 
   /**
    * Returns an array of strings representing the child preferences of the
    * root of this branch.
    * 
    * @param aStartingAt The point on the branch at which to start enumerating
@@ -297,18 +287,17 @@ interface nsIPrefBranch : nsISupports
    *                    preferences referenced by this branch.
    * @param aCount      Receives the number of elements in the array.
    * @param aChildArray Receives the array of child preferences.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on both.
    *
-   * @return NS_OK The preference list was successfully retrieved.
-   * @return Other The preference(s) do not exist or an error occurred.
+   * @throws Error The preference(s) do not exist or an error occurred.
    */
   void getChildList(in string aStartingAt,
                     [optional] out unsigned long aCount,
                     [array, size_is(aCount), retval] out string aChildArray);
 
   /**
    * Called to reset all of the preferences referenced by this branch to their
    * default values.
@@ -316,18 +305,17 @@ interface nsIPrefBranch : nsISupports
    * @param aStartingAt The point on the branch at which to start the resetting
    *                    preferences to their default values. Pass in "" to
    *                    reset all preferences referenced by this branch.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the user branch.
    *
-   * @return NS_OK The preference(s) were successfully reset.
-   * @return Other The preference(s) do not exist or an error occurred.
+   * @throws Error The preference(s) do not exist or an error occurred.
    */
   void resetBranch(in string aStartingAt);
 
   /**
    * Add a preference change observer. On preference changes, the following
    * arguments will be passed to the nsIObserver.observe() method:
    *   aSubject - The nsIPrefBranch object (this)
    *   aTopic   - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID

--- a/modules/libpref/public/nsIPrefLocalizedString.idl
+++ b/modules/libpref/public/nsIPrefLocalizedString.idl
@@ -17,18 +17,17 @@
  */
 
 [scriptable, uuid(ae419e24-1dd1-11b2-b39a-d3e5e7073802)]
 interface nsIPrefLocalizedString : nsISupports
 {
   /**
    * Provides access to string data stored in this property.
    *
-   * @return NS_OK The operation succeeded.
-   * @return Other An error occurred.
+   * @throws Error An error occurred.
    */
   attribute wstring data;
 
   /**
    * Used to retrieve the contents of this object into a wide string.
    *
    * @return wstring The string containing the data stored within this object.
    */
@@ -40,18 +39,16 @@ interface nsIPrefLocalizedString : nsISu
    * @param length The length of the string. This value should not include
    *               space for the null terminator, nor should it account for the
    *               size of a character. It should  only be the number of
    *               characters for which there is space in the string.
    * @param data   The string data to be stored.
    *
    * @note
    * This makes a copy of the string argument passed in.
-   *
-   * @return NS_OK The data was successfully stored.
    */
   void setDataWithLength(in unsigned long length,
                          [size_is(length)] in wstring data);
 };
 
 %{C++
 
 #define NS_PREFLOCALIZEDSTRING_CID                     \

--- a/modules/libpref/public/nsIPrefService.idl
+++ b/modules/libpref/public/nsIPrefService.idl
@@ -34,51 +34,46 @@ interface nsIPrefService : nsISupports
    * Called to read in the preferences specified in a user preference file.
    *
    * @param aFile The file to be read.
    *
    * @note
    * If nullptr is passed in for the aFile parameter the default preferences
    * file(s) [prefs.js, user.js] will be read and processed.
    *
-   * @return NS_OK File was read and processed.
-   * @return Other File failed to read or contained invalid data.
+   * @throws Error File failed to read or contained invalid data.
    *
    * @see savePrefFile
    * @see nsIFile
    */
   void readUserPrefs(in nsIFile aFile);
 
   /**
    * Called to completely flush and re-initialize the preferences system.
    *
-   * @return NS_OK The preference service was re-initialized correctly.
-   * @return Other The preference service failed to restart correctly.
+   * @throws Error The preference service failed to restart correctly.
    */
   void resetPrefs();
 
   /**
    * Called to reset all preferences with user set values back to the
    * application default values.
-   *
-   * @return NS_OK Always.
    */
   void resetUserPrefs();
 
   /**
    * Called to write current preferences state to a file.
    *
    * @param aFile The file to be written.
    *
    * @note
    * If nullptr is passed in for the aFile parameter the preference data is
    * written out to the current preferences file (usually prefs.js.)
    *
-   * @return NS_OK File was written.
-   * @return Other File failed to write.
+   * @throws Error File failed to write.
    *
    * @see readUserPrefs
    * @see nsIFile
    */
   void savePrefFile(in nsIFile aFile);
 
   /**
    * Call to get a Preferences "Branch" which accesses user preference data.

--- a/rdf/base/idl/nsIRDFDataSource.idl
+++ b/rdf/base/idl/nsIRDFDataSource.idl
@@ -16,53 +16,45 @@ interface nsIRDFDataSource : nsISupports
     /** The "URI" of the data source. This used by the RDF service's
      * |GetDataSource()| method to cache datasources.
      */
     readonly attribute string URI;
 
     /** Find an RDF resource that points to a given node over the
      * specified arc & truth value
      *
-     * @return NS_RDF_NO_VALUE if there is no source that leads
+     * @throws NS_RDF_NO_VALUE if there is no source that leads
      * to the target with the specified property.
      */
     nsIRDFResource GetSource(in nsIRDFResource aProperty,
                              in nsIRDFNode     aTarget,
                              in boolean        aTruthValue);
 
     /**
      * Find all RDF resources that point to a given node over the
      * specified arc & truth value
-     *
-     * @return NS_OK unless a catastrophic error occurs. If the
-     * method returns NS_OK, you may assume that nsISimpleEnumerator points
-     * to a valid (but possibly empty) cursor.
      */
     nsISimpleEnumerator GetSources(in nsIRDFResource aProperty,
                                    in nsIRDFNode     aTarget,
                                    in boolean        aTruthValue);
 
     /**
      * Find a child of that is related to the source by the given arc
      * arc and truth value
      *
-     * @return NS_RDF_NO_VALUE if there is no target accessible from the
+     * @throws NS_RDF_NO_VALUE if there is no target accessible from the
      * source via the specified property.
      */
     nsIRDFNode GetTarget(in nsIRDFResource aSource,
                          in nsIRDFResource aProperty,
                          in boolean        aTruthValue);
 
     /**
      * Find all children of that are related to the source by the given arc
      * arc and truth value.
-     *
-     * @return NS_OK unless a catastrophic error occurs. If the
-     * method returns NS_OK, you may assume that nsISimpleEnumerator points
-     * to a valid (but possibly empty) cursor.
      */
     nsISimpleEnumerator GetTargets(in nsIRDFResource aSource,
                                    in nsIRDFResource aProperty,
                                    in boolean aTruthValue);
 
     /**
      * Add an assertion to the graph.
      */
@@ -123,30 +115,22 @@ interface nsIRDFDataSource : nsISupports
 
     /**
      * Remove an observer from this data source.
      */
     void RemoveObserver(in nsIRDFObserver aObserver);
 
     /**
      * Get a cursor to iterate over all the arcs that point into a node.
-     *
-     * @return NS_OK unless a catastrophic error occurs. If the method
-     * returns NS_OK, you may assume that labels points to a valid (but
-     * possible empty) nsISimpleEnumerator object.
      */
     nsISimpleEnumerator ArcLabelsIn(in nsIRDFNode aNode);
 
     /**
      * Get a cursor to iterate over all the arcs that originate in
      * a resource.
-     *
-     * @return NS_OK unless a catastrophic error occurs. If the method
-     * returns NS_OK, you may assume that labels points to a valid (but
-     * possible empty) nsISimpleEnumerator object.
      */
     nsISimpleEnumerator ArcLabelsOut(in nsIRDFResource aSource);
 
     /**
      * Retrieve all of the resources that the data source currently
      * refers to.
      */
     nsISimpleEnumerator GetAllResources();

--- a/xpcom/base/nsIInterfaceRequestor.idl
+++ b/xpcom/base/nsIInterfaceRequestor.idl
@@ -22,16 +22,15 @@
 interface nsIInterfaceRequestor : nsISupports
 {
    /**
     * Retrieves the specified interface pointer.
     *
     * @param uuid The IID of the interface being requested.
     * @param result [out] The interface pointer to be filled in if
     *               the interface is accessible.
-    * @return NS_OK - interface was successfully returned.
-    *         NS_NOINTERFACE - interface not accessible.
-    *         NS_ERROR* - method failure.
+    * @throws NS_NOINTERFACE - interface not accessible.
+    * @throws NS_ERROR* - method failure.
     */
 	void getInterface(in nsIIDRef uuid, 
                       [iid_is(uuid),retval] out nsQIResult result);
 };
 

--- a/xpcom/base/nsIMemory.idl
+++ b/xpcom/base/nsIMemory.idl
@@ -85,17 +85,17 @@ interface nsIMemory : nsISupports
     [noscript, notxpcom] void free(in voidPtr ptr);
 
     /**
      * Attempts to shrink the heap.
      * @param immediate - if true, heap minimization will occur
      *   immediately if the call was made on the main thread. If
      *   false, the flush will be scheduled to happen when the app is
      *   idle.
-     * @return NS_ERROR_FAILURE if 'immediate' is set an the call
+     * @throws NS_ERROR_FAILURE if 'immediate' is set an the call
      *   was not on the application's main thread.
      */
     void heapMinimize(in boolean immediate);
 
     /**
      * This predicate can be used to determine if we're in a low-memory
      * situation (what constitutes low-memory is platform dependent). This
      * can be used to trigger the memory pressure observers.

--- a/xpcom/components/nsIComponentRegistrar.idl
+++ b/xpcom/components/nsIComponentRegistrar.idl
@@ -57,18 +57,17 @@ interface nsIComponentRegistrar : nsISup
      * unregisterFactory
      *
      * Unregister a factory associated with CID aClass.
      *
      * @param aClass   : CID being unregistered
      * @param aFactory : Factory previously registered to create instances of
      *                   CID aClass.
      *
-     * @return NS_OK     Unregistration was successful.
-     *         NS_ERROR* Method failure.
+     * @throws NS_ERROR* Method failure.
      */    
     void unregisterFactory(in nsCIDRef aClass, 
                            in nsIFactory aFactory);
 
     /**
      * registerFactoryLocation
      * @status OBSOLETE: This method is no longer implemented, but preserved
      *                   in this interface for binary compatibility with

--- a/xpcom/components/nsIFactory.idl
+++ b/xpcom/components/nsIFactory.idl
@@ -16,30 +16,27 @@ interface nsIFactory :  nsISupports {
     * Creates an instance of a component.
     *
     * @param aOuter Pointer to a component that wishes to be aggregated
     *               in the resulting instance. This will be nullptr if no
     *               aggregation is requested.
     * @param iid    The IID of the interface being requested in
     *               the component which is being currently created.
     * @param result [out] Pointer to the newly created instance, if successful.
-    * @return NS_OK - Component successfully created and the interface 
-    *                 being requested was successfully returned in result.
-    *         NS_NOINTERFACE - Interface not accessible.
-    *         NS_ERROR_NO_AGGREGATION - if an 'outer' object is supplied, but the
+    * @throws NS_NOINTERFACE - Interface not accessible.
+    * @throws NS_ERROR_NO_AGGREGATION - if an 'outer' object is supplied, but the
     *                                   component is not aggregatable.
     *         NS_ERROR* - Method failure.
     */
     void createInstance(in nsISupports aOuter, in nsIIDRef iid,
                       [retval, iid_is(iid)] out nsQIResult result);
 
    /**
     * LockFactory provides the client a way to keep the component
     * in memory until it is finished with it. The client can call
     * LockFactory(PR_TRUE) to lock the factory and LockFactory(PR_FALSE)
     * to release the factory.	 
     *
     * @param lock - Must be PR_TRUE or PR_FALSE
-    * @return NS_OK - If the lock operation was successful.
-    *         NS_ERROR* - Method failure.
+    * @throws NS_ERROR* - Method failure.
     */
     void lockFactory(in boolean lock);
 };

--- a/xpcom/ds/nsIProperties.idl
+++ b/xpcom/ds/nsIProperties.idl
@@ -10,18 +10,18 @@
  */
 
 [scriptable, uuid(78650582-4e93-4b60-8e85-26ebd3eb14ca)]
 interface nsIProperties : nsISupports
 {
     /**
      * Gets a property with a given name. 
      *
-     * @return NS_ERROR_FAILURE if a property with that name doesn't exist.
-     * @return NS_ERROR_NO_INTERFACE if the found property fails to QI to the 
+     * @throws NS_ERROR_FAILURE if a property with that name doesn't exist.
+     * @throws NS_ERROR_NO_INTERFACE if the found property fails to QI to the 
      * given iid.
      */
     void get(in string prop, in nsIIDRef iid, 
              [iid_is(iid),retval] out nsQIResult result);
 
     /**
      * Sets a property with a given name to a given value. 
      */
@@ -29,17 +29,17 @@ interface nsIProperties : nsISupports
 
     /**
      * Returns true if the property with the given name exists.
      */
     boolean has(in string prop);
 
     /**
      * Undefines a property.
-     * @return NS_ERROR_FAILURE if a property with that name doesn't
+     * @throws NS_ERROR_FAILURE if a property with that name doesn't
      * already exist.
      */
     void undefine(in string prop);
 
     /**
      *  Returns an array of the keys.
      */
     void getKeys(out uint32_t count, [array, size_is(count), retval] out string keys);

--- a/xpcom/ds/nsISimpleEnumerator.idl
+++ b/xpcom/ds/nsISimpleEnumerator.idl
@@ -33,16 +33,14 @@ interface nsISimpleEnumerator : nsISuppo
   /**
    * Called to retrieve the next element in the enumerator. The "next"
    * element is the first element upon the first call. Must be
    * pre-ceeded by a call to hasMoreElements() which returns PR_TRUE.
    * This method is generally called within a loop to iterate over
    * the elements in the enumerator.
    *
    * @see hasMoreElements()
-   * @return NS_OK if the call succeeded in returning a non-null
-   *               value through the out parameter.
-   *         NS_ERROR_FAILURE if there are no more elements
+   * @throws NS_ERROR_FAILURE if there are no more elements
    *                          to enumerate.
    * @return the next element in the enumeration.
    */
   nsISupports getNext();
 };

--- a/xpcom/io/nsIFile.idl
+++ b/xpcom/io/nsIFile.idl
@@ -298,17 +298,17 @@ interface nsIFile : nsISupports
      *  Parent will be null when this is at the top of the volume.
      */
     readonly attribute nsIFile parent;
     
     /**
      *  Returns an enumeration of the elements in a directory. Each
      *  element in the enumeration is an nsIFile.
      *
-     *   @return NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does
+     *   @throws NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does
      *           not specify a directory.
      */
     readonly attribute nsISimpleEnumerator directoryEntries;
 
     /**
      *  initWith[Native]Path
      *
      *  This function will initialize the nsIFile object.  Any

--- a/xpcom/io/nsIOutputStream.idl
+++ b/xpcom/io/nsIOutputStream.idl
@@ -17,19 +17,17 @@ interface nsIInputStream;
  * @param aClosure opaque parameter passed to WriteSegments
  * @param aToSegment pointer to memory owned by the output stream
  * @param aFromOffset amount already written (since WriteSegments was called)
  * @param aCount length of toSegment
  * @param aReadCount number of bytes written
  *
  * Implementers should return the following:
  *
- * @return NS_OK and (*aReadCount > 0) if successfully provided some data
- * @return NS_OK and (*aReadCount = 0) or
- * @return <any-error> if not interested in providing any data
+ * @throws <any-error> if not interested in providing any data
  *
  * Errors are never passed to the caller of WriteSegments.
  */
 typedef NS_CALLBACK(nsReadSegmentFun)(nsIOutputStream *aOutStream,
                                       void *aClosure,
                                       char *aToSegment,
                                       uint32_t aFromOffset,
                                       uint32_t aCount,

--- a/xpcom/io/nsIUnicharInputStream.idl
+++ b/xpcom/io/nsIUnicharInputStream.idl
@@ -17,18 +17,17 @@ interface nsIInputStream;
  * @param aClosure opaque parameter passed to ReadSegments
  * @param aFromSegment pointer to memory owned by the input stream
  * @param aToOffset amount already read (since ReadSegments was called)
  * @param aCount length of fromSegment
  * @param aWriteCount number of bytes read
  *
  * Implementers should return the following:
  *
- * @return NS_OK and (*aWriteCount > 0) if consumed some data
- * @return <any-error> if not interested in consuming any data
+ * @throws <any-error> if not interested in consuming any data
  *
  * Errors are never passed to the caller of ReadSegments.
  *
  * NOTE: returning NS_OK and (*aWriteCount = 0) has undefined behavior.
  */
 typedef NS_CALLBACK(nsWriteUnicharSegmentFun)(nsIUnicharInputStream *aInStream,
                                               void *aClosure,
                                               const PRUnichar *aFromSegment,

--- a/xpcom/threads/nsITimer.idl
+++ b/xpcom/threads/nsITimer.idl
@@ -11,21 +11,16 @@ interface nsIEventTarget;
 %{C++
 /**
  * The signature of the timer callback function passed to initWithFuncCallback.
  * This is the function that will get called when the timer expires if the
  * timer is initialized via initWithFuncCallback.
  *
  * @param aTimer the timer which has expired
  * @param aClosure opaque parameter passed to initWithFuncCallback
- *
- * Implementers should return the following:
- *
- * @return NS_OK
- *
  */
 class nsITimer;
 typedef void (*nsTimerCallbackFunc) (nsITimer *aTimer, void *aClosure);
 %}
 
 native nsTimerCallbackFunc(nsTimerCallbackFunc);
 
 /**