The documentation of TextArea.replaceRange (below) is incorrect.

The text at the start position will not be included in the final string,
but the text at the end position will.

    /**
     * Replaces text between the indicated start and end positions
     * with the specified replacement text. The text at the
     * start and end positions will be included in the final
     * string. The inserted substring may be of a different
     * length than the original.
     *
     * @param str the text to use as the replacement
     * @param start the start position
     * @param end the end position
     * @see java.awt.TextArea#insert
     * @since JDK1.1
     */
    public void replaceRange(String str, int start, int end) {
        replaceText(str, start, end);
    }

    /**
     * @deprecated As of JDK version 1.1,
     * replaced by <code>replaceRange(String, int, int)</code>.
     */
    public synchronized void replaceText(String str, int start, int end) {
        TextAreaPeer peer = (TextAreaPeer)this.peer;
        if (peer != null) {
            peer.replaceText(str, start, end);
        } else {
            text = text.substring(0, start) + str + text.substring(end);
        }
    }

See java.lang.String.substring for examples of how substring behaves.
We should probably add similar examples to the description of replaceRange.

Also, replaceRange throws the same exceptions that substring does,
since the function calls substring. I believe this means that replaceRange
should have an @exception tag similar to the ones in substring(int, int)
and substring(int).

See also the description of
TextComponent.select(int selectionStart, int selectionEnd)
for an similar API. The behavior may not be the same as
TextArea.replaceRange, but the description covers similar issues, and is
fairly complete.
  
Note: we should probably write regression tests for TextArea.replaceRange()
similar to /test/java/awt/TextComponent/SelectionBounds/

Note: should we specify what happens if the string passed into the
function is null?