From a58630bccf25d392871667d1bf2c017056941c20 Mon Sep 17 00:00:00 2001
From: Rick Ossendrijver <rick.ossendrijver@gmail.com>
Date: Fri, 19 Aug 2022 13:33:23 +0200
Subject: [PATCH] Improve `StreamMapToOptionalGet` Refaster template
 documentation (#203)

---
 .../refastertemplates/OptionalTemplates.java        | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/OptionalTemplates.java b/error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/OptionalTemplates.java
index f35bd720a3..ea645ecfa6 100644
--- a/error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/OptionalTemplates.java
+++ b/error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/OptionalTemplates.java
@@ -239,9 +239,16 @@ Stream<T> after(Stream<Optional<T>> stream) {
     }
   }
 
-  /** Within a stream's map operation unconditional {@link Optional#get()} calls can be avoided. */
-  // XXX: An alternative approach is to `.flatMap(Optional::stream)`. That may be a bit longer, but
-  // yield nicer code. Think about it.
+  /**
+   * Within a stream's map operation unconditional {@link Optional#orElseThrow()} calls can be
+   * avoided.
+   *
+   * <p><strong>Warning:</strong> this rewrite rule is not completely behavior preserving. The
+   * original code throws an exception if the mapping operation does not produce a value, while the
+   * replacement does not.
+   */
+  // XXX: An alternative approach is to use `.flatMap(Optional::stream)`. That may be a bit longer,
+  // but yields nicer code. Think about it.
   abstract static class StreamMapToOptionalGet<T, S> {
     @Placeholder
     abstract Optional<S> toOptionalFunction(@MayOptionallyUse T element);