Last Comment Bug 406336 - nsIArray documentation (IndexOf, enumerate) is wrong.
: nsIArray documentation (IndexOf, enumerate) is wrong.
Status: RESOLVED FIXED
: dev-doc-complete
Product: Core
Classification: Components
Component: XPCOM (show other bugs)
: Trunk
: All All
: -- normal (vote)
: mozilla13
Assigned To: :aceman
:
Mentors:
http://bonsai.mozilla.org/cvsblame.cg...
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2007-12-01 10:44 PST by Mark Banner (:standard8)
Modified: 2012-02-22 16:01 PST (History)
3 users (show)
See Also:
Crash Signature:
(edit)
QA Whiteboard:
Iteration: ---
Points: ---
Has Regression Range: ---
Has STR: ---


Attachments
patch for nsIArray.idl (1.32 KB, patch)
2012-02-17 14:07 PST, :aceman
benjamin: review+
Details | Diff | Splinter Review

Description Mark Banner (:standard8) 2007-12-01 10:44:46 PST
nsIArray is a frozen interface, but its documentation is wrong:

indexOf() states that it:
@throws NS_ERROR_NOT_FOUND if the element was not in the array.

That's incorrect, it throws NS_ERROR_FAILURE: http://bonsai.mozilla.org/cvsblame.cgi?file=/mozilla/xpcom/ds/nsArray.cpp&rev=1.14&mark=89,96#81

enumerate() also states that it:
@throws NS_ERROR_FAILURE if the array is empty (to make it easy to detect errors)

If you follow it through to NS_NewArrayEnumerator (http://bonsai.mozilla.org/cvsblame.cgi?file=/mozilla/xpcom/glue/nsArrayEnumerator.cpp&rev=1.15&mark=111-121#111), you'll find that empty arrays are allowed. You may get NS_ERROR_OUT_OF_MEMORY thrown if we're out of memory of course...

So, should we fix the documentation, or the code?

In the IndexOf case NS_ERROR_NOT_FOUND isn't currently a provided error code, and the enumerate case I think it should just accept it as otherwise we're changing the functionality that folks may be relying on.
Comment 1 Kent James (:rkent) 2011-08-05 11:17:16 PDT
I just got caught by this.

"So, should we fix the documentation, or the code?"

Easier just to change the documentation.
Comment 2 :aceman 2012-02-17 14:00:17 PST
I'll fix the docs, as there is no NS_ERROR_NOT_FOUND defined in http://mxr.mozilla.org/comm-central/source/mozilla/xpcom/base/nsError.h .
Comment 3 :aceman 2012-02-17 14:07:41 PST
Created attachment 598369 [details] [diff] [review]
patch for nsIArray.idl

Also patch the comments in code.
Comment 4 :aceman 2012-02-17 14:20:37 PST
Somebody also needs to update https://developer.mozilla.org/en/NsIArray . I had an account there but now it does not work due to BrowserID.
Comment 5 :aceman 2012-02-21 11:28:30 PST
I could now finally login into MDN so I fixed the docs too.
Comment 7 Ed Morley [:emorley] 2012-02-22 16:01:30 PST
https://hg.mozilla.org/mozilla-central/rev/3ed99fc9760a

Note You need to log in before you can comment on or make changes to this bug.