Bug 331566 - Change idl interfaces to use @throws instead of @return NS_. r=bsmedberg
authorMaria Grazia Alastra <alastra.mariagrazia@gmail.com>
Thu, 16 May 2013 08:26:55 -0400
changeset 132085 fcfeafc7cf398ab7488855616882606f928f0514
parent 132084 bf5d4c608c3670637bb16972e195d095bdf509c9
child 132086 b3e95646e451849611632b63a52efa8e363049c2
push id24683
push userryanvm@gmail.com
push dateThu, 16 May 2013 20:16:53 +0000
treeherdermozilla-central@8d7691da4700 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersbsmedberg
bugs331566
milestone24.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 331566 - Change idl interfaces to use @throws instead of @return NS_. r=bsmedberg
content/base/public/nsISelectionDisplay.idl
docshell/base/nsIWebPageDescriptor.idl
embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl
image/public/imgICache.idl
modules/libpref/public/nsIPrefBranch.idl
modules/libpref/public/nsIPrefLocalizedString.idl
modules/libpref/public/nsIPrefService.idl
rdf/base/idl/nsIRDFDataSource.idl
xpcom/base/nsIInterfaceRequestor.idl
xpcom/base/nsIMemory.idl
xpcom/components/nsIComponentRegistrar.idl
xpcom/components/nsIFactory.idl
xpcom/ds/nsIProperties.idl
xpcom/ds/nsISimpleEnumerator.idl
xpcom/io/nsIFile.idl
xpcom/io/nsIOutputStream.idl
xpcom/io/nsIUnicharInputStream.idl
xpcom/threads/nsITimer.idl
--- 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);
 
 /**