8151531: Add notes to BaseStream.spliterator/iterator docs regarding them being escape hatches

Reviewed-by: psandoz

Author: viktorklang-ora

src/java.base/share/classes/java/util/stream/BaseStream.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -69,6 +69,11 @@ public interface BaseStream<T, S extends BaseStream<T, S>>
      * <p>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
+     * @apiNote
+     * This operation is provided as an "escape hatch" to enable
+     * arbitrary client-controlled pipeline traversals in the event that the
+     * existing operations are not sufficient to the task.
+     *
      * @return the element iterator for this stream
      */
     Iterator<T> iterator();
@@ -79,6 +84,11 @@ public interface BaseStream<T, S extends BaseStream<T, S>>
      * <p>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
+     * @apiNote
+     * This operation is provided as an "escape hatch" to enable
+     * arbitrary client-controlled pipeline traversals in the event that the
+     * existing operations are not sufficient to the task.
+     *
      * <p>
      * The returned spliterator should report the set of characteristics derived
      * from the stream pipeline (namely the characteristics derived from the