A DESCRIPTION OF THE PROBLEM :
replace(CharSequence target, CharSequence replacement)
"Replaces each substring of this string" is misleading, particularly for beginners.
replaceAll and replaceFirst have the same problem.
Please be consistent.

A similar bug report was answered with "It's a matter of interpretation."
I don't want to INTERPRET Javadoc. It isn't an English essay in school. It should be clear, concise and NOT open to interpretation.
Thanks! :-)

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The description for
replace(char oldChar, char newChar)
is better:
"_RETURNS_ a string resulting from replacing..."
ACTUAL -
"Replaces each substring of this string"

URL OF FAULTY DOCUMENTATION :
https://docs.oracle.com/javase/8/docs/api/java/lang/String.html