331566 - please change idl interfaces to use @throws instead of @return NS_

Status: RESOLVED FIXED

(Core :: XPCOM, enhancement, P3)

Description

[timeless]

steps to reproduce: visit mxr-test/seamonkey/search

Search for:   @return
 
 Regular Expression Search  
Find files matching:  idl$
Limit output to pattern:  NS_

Expected results: @return is supposed to be used for return values, which are idl types. nsresults are usually @throws

Actual results:

These files were searched.

Found 102 matching lines

@return
/toolkit/components/startup/public/nsIAppStartup.idl, line 58 -- * @returnCode NS_SUCCESS_RESTART_APP
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 99 -- * @returns NS_OK if all memory allocated properly and the IPC service was
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 102 -- * @returns an NS_ERROR_<foo> code specific to the failure otherwise
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 134 -- * @returns NS_OK if the attach message was sent to the Transaction Manager.
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 136 -- * @returns an NS_ERROR_<foo> code specific to the failure otherwise
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 159 -- * @returns NS_OK if the detach message is sent to the Transaction Manager
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 161 -- * @returns NS_ERROR_FAILURE is something goes wrong
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 163 -- * @returns NS_ERRROR_UNEXPECTD if the domain does not have an observer 
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 187 -- * @returns NS_OK if the flush message is sent to the Transaction Manager
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 189 -- * @returns NS_ERROR_FAILURE is something goes wrong
/ipc/ipcd/extensions/transmngr/public/ipcITransactionService.idl, line 191 -- * @returns NS_ERRROR_UNEXPECTD if the domain does not have an observer 
/modules/libpr0n/public/imgICache.idl, line 68 -- * @return NS_OK if \a uri was removed from the cache.
/modules/plugin/base/public/nsILegacyPluginWrapperOS2.idl, line 74 -- * @returns NS_OK on success.
/modules/plugin/base/public/nsILegacyPluginWrapperOS2.idl, line 75 -- * @returns NS_ERROR_NO_INTERFACE if aIID isn't supported. aOut is nsnull.
/modules/plugin/base/public/nsILegacyPluginWrapperOS2.idl, line 76 -- * @returns NS_ERROR_FAILURE on other error. aOut undefined.
/modules/oji/public/nsIJVMAuthTools.idl, line 80 -- * @return NS_OK if success, other if fail
/modules/oji/public/nsIJVMAuthTools.idl, line 100 -- * @return NS_OK if success, other if fail
/modules/libpref/public/nsIPrefService.idl, line 69 -- * @return NS_OK File was read and processed.
/modules/libpref/public/nsIPrefService.idl, line 80 -- * @return NS_OK The preference service was re-initialized correctly.
/modules/libpref/public/nsIPrefService.idl, line 89 -- * @return NS_OK Always.
/modules/libpref/public/nsIPrefService.idl, line 102 -- * @return NS_OK File was written.
/modules/libpref/public/nsIPrefBranch.idl, line 107 -- * @return NS_OK The value was successfully set.
/modules/libpref/public/nsIPrefBranch.idl, line 131 -- * @return NS_OK The value was successfully set.
/modules/libpref/public/nsIPrefBranch.idl, line 155 -- * @return NS_OK The value was successfully set.
/modules/libpref/public/nsIPrefBranch.idl, line 177 -- * @return NS_OK The value was successfully retrieved.
/modules/libpref/public/nsIPrefBranch.idl, line 200 -- * @return NS_OK The value was successfully set.
/modules/libpref/public/nsIPrefBranch.idl, line 217 -- * @return NS_OK The user preference was successfully cleared.
/modules/libpref/public/nsIPrefBranch.idl, line 233 -- * @return NS_OK The preference was successfully locked.
/modules/libpref/public/nsIPrefBranch.idl, line 284 -- * @return NS_OK The preference was successfully unlocked.
/modules/libpref/public/nsIPrefBranch.idl, line 303 -- * @return NS_OK The preference(s) were successfully removed.
/modules/libpref/public/nsIPrefBranch.idl, line 322 -- * @return NS_OK The preference list was successfully retrieved.
/modules/libpref/public/nsIPrefBranch.idl, line 340 -- * @return NS_OK The preference(s) were successfully reset.
/modules/libpref/public/nsISecurityPref.idl, line 72 -- * @return NS_OK The value was successfully set.
/modules/libpref/public/nsISecurityPref.idl, line 96 -- * @return NS_OK The value was successfully set.
/modules/libpref/public/nsISecurityPref.idl, line 120 -- * @return NS_OK The value was successfully set.
/modules/libpref/public/nsISecurityPref.idl, line 137 -- * @return NS_OK The user preference was successfully cleared.
/modules/libpref/public/nsIPrefLocalizedString.idl, line 61 -- * @return NS_OK The operation succeeded.
/modules/libpref/public/nsIPrefLocalizedString.idl, line 85 -- * @return NS_OK The data was successfully stored.
/netwerk/base/public/nsIAuthPromptProvider.idl, line 62 -- * @returns a nsIAuthPrompt interface, or throws NS_ERROR_NOT_AVAILABLE
/content/base/public/nsISelectionDisplay.idl, line 57 -- @return NS_OK if successful.
/content/base/public/nsISelectionDisplay.idl, line 67 -- @return NS_OK if successful.
/content/base/public/nsISelectionController.idl, line 119 -- * @return always NS_OK
/content/base/public/nsISelectionController.idl, line 128 -- * @return always NS_OK
/content/base/public/nsISelectionController.idl, line 135 -- * @return if aOutEnabled==null, returns NS_ERROR_INVALID_ARG
/content/base/public/nsISelectionController.idl, line 144 -- * @return always NS_OK
/docshell/shistory/public/nsISHistory.idl, line 103 -- * @return <code>NS_OK</code> history entry for 
/docshell/base/nsIWebPageDescriptor.idl, line 55 -- * @return NS_OK - 
/docshell/base/nsIScrollable.idl, line 70 -- @return NS_OK - Setting or Getting completed successfully.
/docshell/base/nsIScrollable.idl, line 87 -- @return NS_OK - Setting or Getting completed successfully.
/mailnews/addrbook/public/nsILDAPPrefsService.idl, line 70 -- * @return NS_OK The preference list was successfully retrieved.
/widget/public/nsIFormatConverter.idl, line 74 -- * @returns returns NS_OK if it was converted
/widget/public/nsIBaseWindow.idl, line 87 -- @return NS_OK - Window Init succeeded without a problem.
/widget/public/nsIBaseWindow.idl, line 102 -- @return NS_OK - Creation was successfull.
/widget/public/nsIBaseWindow.idl, line 115 -- @return NS_OK - Everything destroyed properly.
/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl, line 122 -- * @return NS_OK Operation was successful or is still ongoing.
/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl, line 123 -- * @return NS_BINDING_ABORTED Operation cancelled.
/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl, line 124 -- * @return NS_ERROR_FAILURE Non-specific failure.
/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl, line 161 -- * @return NS_OK Operation has been started.
/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl, line 162 -- * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl, line 271 -- * @return NS_OK Operation has been started.
/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl, line 272 -- * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
/embedding/browser/webBrowser/nsITooltipListener.idl, line 69 -- * @return <code>NS_OK</code> if the tooltip was displayed.
/embedding/browser/webBrowser/nsIEmbeddingSiteWindow.idl, line 97 -- * @return <code>NS_OK</code> if operation was performed correctly;
/embedding/browser/webBrowser/nsIContextMenuListener2.idl, line 140 -- * @return <CODE>NS_OK</CODE> if successful, otherwise <CODE>NS_ERROR_FAILURE</CODE> if no
/embedding/browser/webBrowser/nsIContextMenuListener2.idl, line 152 -- * @return <CODE>NS_OK</CODE> if successful, otherwise <CODE>NS_ERROR_FAILURE</CODE> if no background
/embedding/browser/webBrowser/nsIWebBrowser.idl, line 72 -- * @return <CODE>NS_OK</CODE> for successful registration;
/embedding/browser/webBrowser/nsIWebBrowser.idl, line 84 -- * @return <CODE>NS_OK</CODE>, listener was successfully added;
/embedding/browser/webBrowser/nsIWebBrowser.idl, line 98 -- * @return <CODE>NS_OK</CODE>, listener was successfully removed;
/embedding/browser/webBrowser/nsIContextMenuListener.idl, line 96 -- * @return <CODE>NS_OK</CODE> always.
/editor/idl/nsIHTMLEditor.idl, line 454 -- * @return NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
/editor/idl/nsIHTMLEditor.idl, line 476 -- * @return NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
/editor/idl/nsIEditor.idl, line 208 -- * @return if aEnable is PR_TRUE, returns NS_OK if
/intl/unicharutil/idl/nsIUnicodeNormalizer.idl, line 59 -- * @return NS_OK for success, 
/rdf/base/idl/rdfITripleVisitor.idl, line 59 -- * @returnCode NS_RDF_STOP_VISIT to stop iterating over the query result.
/rdf/base/idl/nsIRDFDataSource.idl, line 61 -- * @return NS_RDF_NO_VALUE if there is no source that leads
/rdf/base/idl/nsIRDFDataSource.idl, line 72 -- * @return NS_OK unless a catastrophic error occurs. If the
/rdf/base/idl/nsIRDFDataSource.idl, line 84 -- * @return NS_RDF_NO_VALUE if there is no target accessible from the
/rdf/base/idl/nsIRDFDataSource.idl, line 95 -- * @return NS_OK unless a catastrophic error occurs. If the
/rdf/base/idl/nsIRDFDataSource.idl, line 169 -- * @return NS_OK unless a catastrophic error occurs. If the method
/rdf/base/idl/nsIRDFDataSource.idl, line 179 -- * @return NS_OK unless a catastrophic error occurs. If the method
/xpcom/components/nsIFactory.idl, line 58 -- * @return NS_OK - Component successfully created and the interface 
/xpcom/components/nsIFactory.idl, line 75 -- * @return NS_OK - If the lock operation was successful.
/xpcom/components/nsIComponentRegistrar.idl, line 86 -- * @return NS_OK Unregistration was successful.
/xpcom/components/nsIComponentRegistrar.idl, line 102 -- * @return NS_OK Registration was successful.
/xpcom/components/nsIComponentRegistrar.idl, line 119 -- * @return NS_OK Unregistration was successful.
/xpcom/components/nsIComponentRegistrar.idl, line 145 -- * @return NS_OK Registration was successful.
/xpcom/components/nsIComponentRegistrar.idl, line 163 -- * @return NS_OK Unregistration was successful.
/xpcom/threads/nsITimer.idl, line 55 -- * @return NS_OK
/xpcom/threads/nsIEventQueueService.idl, line 81 -- * @return NS_OK on success, or a host of failure indications
/xpcom/threads/nsIEventQueueService.idl, line 88 -- * @return NS_OK on success, or a host of failure indications
/xpcom/ds/nsIProperties.idl, line 51 -- * @return NS_ERROR_FAILURE if a property with that name doesn't exist.
/xpcom/ds/nsIProperties.idl, line 52 -- * @return NS_ERROR_NO_INTERFACE if the found property fails to QI to the 
/xpcom/ds/nsIProperties.idl, line 70 -- * @return NS_ERROR_FAILURE if a property with that name doesn't
/xpcom/ds/nsISimpleEnumerator.idl, line 74 -- * @return NS_OK if the call succeeded in returning a non-null
/xpcom/io/nsIOutputStream.idl, line 59 -- * @return NS_OK and (*aReadCount > 0) if successfully provided some data
/xpcom/io/nsIOutputStream.idl, line 60 -- * @return NS_OK and (*aReadCount = 0) or
/xpcom/io/nsIInputStream.idl, line 58 -- * @return NS_OK and (*aWriteCount > 0) if consumed some data
/xpcom/io/nsIUnicharInputStream.idl, line 56 -- * @return NS_OK and (*aWriteCount > 0) if consumed some data
/xpcom/io/nsIFile.idl, line 333 -- * @return NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does
/xpcom/io/nsIDirectoryService.idl, line 93 -- * @returnCode NS_SUCCESS_AGGREGATE_RESULT if this result should be
/xpcom/base/nsIMemory.idl, line 118 -- * @return NS_ERROR_FAILURE if 'immediate' is set an the call
/xpcom/base/nsIInterfaceRequestor.idl, line 65 -- * @return NS_OK - interface was successfully returned.

This page was automatically generated by MXR-test.

Comment 1

[Daniel Brooks [:db48x]]

Attachment: 331566-1.diff

Comment 2

[Daniel Brooks [:db48x]]

I'm not as sure about this one, because now we've got things that say @throws NS_OK, which is a little weird. Throwing NS_OK is a lot like not throwing, if you ask me.

Comment 3

[timeless]

Comment on attachment 216180 [details] [diff] [review]
331566-1.diff

yeah, the NS_OK cases shouldn't be listed as throwing. sorta swallow them and list what's left instead.

Comment 4

[Maria Grazia Alastra [:mga]]

Attachment: Change idl interfaces to use @throws instead of @return NS_ and cut off NS_OK

Comment 5

[Benjamin Smedberg]

Comment on attachment 747543 [details] [diff] [review]
Change idl interfaces to use @throws instead of @return NS_ and cut off NS_OK

I don't think that "@throws Other" makes a lot of sense. I think we put in "Other" to compare it with NS_OK, but now that you're removing the NS_OK, Other just looks out of place. Unfortunately, we have to have *something* there to suit the doxygen parser:

http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdthrow

So I think you want "@throws Error if setting failed or the value is the wrong type."

Comment 6

[Maria Grazia Alastra [:mga]]

Attachment: Use @throw instead of @return NS_ in idl interfaces (v2)

Sorry, that "Other" was indeed a bit unconvincing, I should have asked. I hope the patch is ok this time :)

Comment 7

[Maria Grazia Alastra [:mga]]

The patch applies smoothly with the latest version of the mozilla-central code.

Comment 8

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/integration/mozilla-inbound/rev/fcfeafc7cf39

Comment 9

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/mozilla-central/rev/fcfeafc7cf39