RFR: 8023997 : j.l.String.join(java.lang.CharSequence, java.lang.Iterable) sample doesn't compile and is incorrect

[Henry Jen]

On 08/30/2013 12:53 AM, Alan Bateman wrote:
> On 30/08/2013 07:44, Henry Jen wrote:
>> Hi,
>>
>> Please kindly review a simple webrev that just fixes a sample in the
>> javadoc of String.join().
>>
>> http://cr.openjdk.java.net/~henryjen/tl/8023997/0/webrev/
>>
> This looks okay to me.
> 

Thanks, I pushed it as is.

> I note in the bug report that the example is considered normative but
> that doesn't seem right (at least I've always thought of examples/code
> fragments in the javadoc as just helpful, but non-normative, text). So
> maybe the bug report is also looking for @apiNote to be added?
> 

I tend to agree. I leave it for now because

- Other methods in String have code examples documented the same way
- In some sense, the example helps to clarify spec, and itself like test
cases.

If this matters much, should we file a bug to review code examples in
String and decide what is proper for each example? In this case, I do
feel it is redundant as there are two examples. Perhaps the second one
should remain HashSet as a special note that Iterable sequence matters.

Cheers,
Henry