JDK-8187652 : (spec str) clarify specs of String.replace, replaceFirst, replaceAll
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 8,9
  • Priority: P5
  • Status: Open
  • Resolution: Unresolved
  • Submitted: 2017-09-15
  • Updated: 2017-09-19
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbd_majorUnresolved
Related Reports
Relates :  
JDK-8138614 - (spec str) StringBuffer and StringBuilder methods improperly require "new" String to be returned
Description
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
Comments
Though this may seem trivial, I've seen sample code make this mistake, so a clarification seems helpful. The suggestion to follow replace(char, char) wording "Returns the result of ..." is sensible. Care should be taken not to overspecify here. It should not say "returns a new string" since it's possible no replacements were done, and the implementation could simply return 'this'. However, it should also not require that 'this' be returned if no replacements were done, as is done elsewhere. See also these other methods that have specs that seem like mutation, or that overspecify return value behavior: concat replace(char, char) split join(cs, cs...) join(cs, Iterable) toLowerCase() toLowerCase(Locale) toUpperCase() toUpperCase(Locale) trim See also: JDK-8138614 regarding similar issues with methods of StringBuilder and StringBuffer.
19-09-2017