406336 - nsIArray documentation (IndexOf, enumerate) is wrong.

Status: RESOLVED FIXED

(Core :: XPCOM, defect)

Description

[Mark Banner (:standard8)]

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)]

I just got caught by this.

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

Easier just to change the documentation.

Comment 2

[:aceman]

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]

Attachment: patch for nsIArray.idl

Also patch the comments in code.

Comment 4

[:aceman]

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]

I could now finally login into MDN so I fixed the docs too.

Comment 6

[Dão Gottwald [:dao]]

http://hg.mozilla.org/integration/mozilla-inbound/rev/3ed99fc9760a

Comment 7

[Ed Morley [:emorley]]

https://hg.mozilla.org/mozilla-central/rev/3ed99fc9760a