Imprecise javadoc of javax.swing.text.Element.getElement(int index)

The present javadoc of javax.swing.text.Element.getElement(index) is

   /**
    * Fetches the child element at the given index.
    *
    * @param index the specified index >= 0
    * @return the child element
    */
   public Element getElement(int index);

It does not mention what happens for invalid index values at all.

The javadoc of AbstractDocument.BranchElement is

   /**
    * Gets a child element.
    *
    * @param index the child index, >= 0 && < getElementCount()
    * @return the child element, null if none
    */
   public Element getElement(int index) {
       if (index < nchildren) {
           return children[index];
       }
       return null;
   }

which is more precise but please note that the implementation does not fulfil the javadoc for (index < 0) because in that case the IndexOutOfBoundsException will be thrown which is not documented.
IMO returning null for invalid indices is unfortunate as it leads to less readable code (extra checks for returned null element should be present and if they are not present the code will likely fail later with NullPointerException and it may not be immediately visible what was the cause of the problem). If the IOOBE would be thrown consistently for any (index < 0 || index >= getElementCount()) then the code would fail fast and the getElement() could better annotate the exception e.g. mentioning requested index value and the getElementCount() value in the exception.
Unfortunately there is already code relying on null being returned from getElement() e.g. in HTMLEditorKit.
Please note that the similar applies for javax.swing.text.View.getView(int index).

I propose to at least change the javadoc of javax.swing.text.Element.getElement(index) to the javadoc similar to BranchElement.getElement().

###@###.### 2005-05-04 15:32:57 GMT