<html><body><div dir="ltr">Hi core libs team,</div><div dir="ltr"><br></div><div dir="ltr">I think I found a rather inconsequential and esoteric bug, though the term is somewhat less objectively defined when the problem exists solely in how complete some method’s javadoc is.<br></div><div><br></div><div dir="ltr">Two questions: Is there a plausible argument that the javadoc as is, shouldn’t be updated? If not, what’s the right place to report this javadoc ‘bug’?<br><div><br></div><div dir="ltr">The issue:</div><div><div><br></div><div dir="ltr">A snippet of the javadoc of Collection.toArray, from current HEAD jdk22u:</div><div dir="ltr"><br></div><div dir="ltr"> <p>The returned array will be "safe" in that no references to it are</div><div dir="ltr"> * maintained by this collection. (In other words, this method must</div><div dir="ltr"> * allocate a new array even if this collection is backed by an array).</div><div dir="ltr"> * The caller is thus free to modify the returned array.</div><div dir="ltr"><br></div><div dir="ltr">The javadoc of Stream.toArray, from current HEAD jdk22u - has no such rider anywhere in its documentation nor on the javadoc of the Stream interface, nor on the package javadoc. The javadoc is quite short; the complete docs on toArray():</div><div dir="ltr"><br></div><div dir="ltr"> /**</div><div dir="ltr"> * Returns an array containing the elements of this stream.</div><div dir="ltr"> *</div><div dir="ltr"> * <p>This is a <a href="package-summary.html#StreamOps">terminal</div><div dir="ltr"> * operation</a>.</div><div dir="ltr"> *</div><div dir="ltr"> * @return an array, whose {@linkplain Class#getComponentType runtime component</div><div dir="ltr"> * type} is {@code Object}, containing the elements of this stream</div><div dir="ltr"> */</div><div dir="ltr"><br></div><div dir="ltr">The more usually used variant taking a function that makes the array has slightly longer javadoc, but it similarly makes no mention whatsoever about the contract stipulation that any implementors must not keep a reference.</div><div dir="ltr"><br></div><div dir="ltr">A snippet from Stuart Marks on a stack overflow question about a to the asker weird choice about stream’s toList()’s default implementation (<a href="https://stackoverflow.com/questions/77473755/is-it-necessary-to-copy-a-list-to-be-safe/77474199?noredirect=1#comment136909551_77474199">https://stackoverflow.com/questions/77473755/is-it-necessary-to-copy-a-list-to-be-safe/77474199?noredirect=1#comment136909551_77474199</a>):</div><div dir="ltr"><br></div><div dir="ltr"> <span class="comment-copy" style="margin:0px;padding:0px;border:0px;font-variant-ligatures:normal;font-variant-numeric:inherit;font-variant-east-asian:inherit;font-variant-alternates:inherit;font-stretch:inherit;line-height:inherit;font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-kerning:inherit;font-feature-settings:inherit;vertical-align:baseline;box-sizing:inherit;color:rgb(12,13,14);text-decoration-style:initial;text-decoration-color:initial">@Holger The extra step in the default implementation is there to force a defensive copy if <code style="margin:0px;padding:1px 5px;border:0px;font-style:inherit;font-variant-ligatures:inherit;font-variant-caps:inherit;font-variant-alternates:inherit;font-variant-numeric:inherit;font-variant-east-asian:inherit;font-stretch:inherit;line-height:inherit;font-family:var(--ff-mono);font-kerning:inherit;font-feature-settings:inherit;vertical-align:baseline;box-sizing:inherit;white-space:pre-wrap">this.toArray</code> were to violate its spec and keep a reference to the returned array. Without the defensive copy, it would be possible to modify the list returned from the default <code style="margin:0px;padding:1px 5px;border:0px;font-style:inherit;font-variant-ligatures:inherit;font-variant-caps:inherit;font-variant-alternates:inherit;font-variant-numeric:inherit;font-variant-east-asian:inherit;font-stretch:inherit;line-height:inherit;font-family:var(--ff-mono);font-kerning:inherit;font-feature-settings:inherit;vertical-align:baseline;box-sizing:inherit;white-space:pre-wrap">toList</code> implementation.</span><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"> </span></div><div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"><br></span></div><div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"><br></span></div><div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial">Which leads to the obvious question: Where is that ’spec’ that Stuart is referring to? Either the javadoc is the spec and therefore the javadoc is buggy, in that it fails to mention this stipulation, or the spec is elsewhere, in which case surely the javadoc should link to it or copy it.</span></div><div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"><br></span></div><div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial">Possibly this is jus filed away as: “Unlike with Collection, Stream instances are disposable; after a terminal operation (and toArray is terminal) has been invoked on it, that stream object has ceased being useful. Therefore, there is no perceived value to caching any created array, therefore, it doesn’t need mentioning".</span></div><div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"><br></span></div><div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe UI Adjusted","Segoe UI","Liberation Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial">Except, as per Stuart’s comment, actual OpenJDK code is written partly to deal with any violators of this invisible spec, and the discrepancy (where Collection.toArray explicitly mentions the contract stipulation that toArray() must make safe arrays, but Stream’s toArray() does not) suggests a fundamental difference where none exists (in fact, literally: Apparently its a spec violation if your Stream implementation return a non-safe array from toArray!)</span></div><div dir="ltr"><br></div><div dir="ltr"> --Reinier Zwitserloot<br></div></div></div></body></html>