Copilot commented on code in PR #2363:
URL: https://github.com/apache/pekko/pull/2363#discussion_r2462677623
##########
stream/src/main/scala/org/apache/pekko/stream/scaladsl/Flow.scala:
##########
@@ -1567,6 +1567,21 @@ trait FlowOps[+Out, +Mat] {
def filterNot(p: Out => Boolean): Repr[Out] =
via(Flow[Out].filter(!p(_)).withAttributes(DefaultAttributes.filterNot and
SourceLocation.forLambda(p)))
+ /**
+ * Run the given function when the first element is received.
+ *
+ * '''Emits when''' the mapping function returns an element
Review Comment:
The documentation incorrectly states that emissions occur when 'the mapping
function returns an element.' The `doOnFirst` operator doesn't map elements; it
executes a side-effecting function on the first element and passes all elements
through unchanged. Update the documentation to reflect that it emits when
upstream emits.
```suggestion
* '''Emits when''' upstream emits an element
```
##########
docs/src/main/paradox/stream/operators/Source-or-Flow/doOnFirst.md:
##########
@@ -0,0 +1,31 @@
+# doOnFirst
+
+Run the given function when the first element is received.
+
+@ref[Simple operators](../index.md#simple-operators)
+
+## Signature
+
+@apidoc[Source.doOnFirst](Source) {
scala="#doOnFirst(f:Out=>Unit):FlowOps.this.Repr[Out]"
java="#map(org.apache.pekko.japi.function.Procedure)" }
+@apidoc[Flow.doOnFirst](Flow) {
scala="#doOnFirst(f:Out=>Unit):FlowOps.this.Repr[Out]"
java="#map(org.apache.pekko.japi.function.Procedure)" }
+
+## Description
+
+Run the given function when the first element is received.
+
+## Examples
+
+Scala
+: @@snip [Flow.scala](/docs/src/test/scala/docs/stream/operators/Map.scala) {
#imports #map }
+
+## Reactive Streams semantics
+
+@@@div { .callout }
+
+**emits** when the mapping function returns an element
Review Comment:
The reactive streams semantics incorrectly describe emissions as occurring
when 'the mapping function returns an element.' The `doOnFirst` operator is a
passthrough that emits when upstream emits (after executing the side effect on
the first element). Update to 'emits when upstream emits an element'.
```suggestion
**emits** when upstream emits an element
```
##########
docs/src/main/paradox/stream/operators/Source-or-Flow/doOnFirst.md:
##########
@@ -0,0 +1,31 @@
+# doOnFirst
+
+Run the given function when the first element is received.
+
+@ref[Simple operators](../index.md#simple-operators)
+
+## Signature
+
+@apidoc[Source.doOnFirst](Source) {
scala="#doOnFirst(f:Out=>Unit):FlowOps.this.Repr[Out]"
java="#map(org.apache.pekko.japi.function.Procedure)" }
+@apidoc[Flow.doOnFirst](Flow) {
scala="#doOnFirst(f:Out=>Unit):FlowOps.this.Repr[Out]"
java="#map(org.apache.pekko.japi.function.Procedure)" }
+
+## Description
+
+Run the given function when the first element is received.
+
+## Examples
+
+Scala
+: @@snip [Flow.scala](/docs/src/test/scala/docs/stream/operators/Map.scala) {
#imports #map }
Review Comment:
The documentation snippet references the wrong file and snippet tags. It
points to 'Map.scala' and '#map' instead of 'DoOnFirst.scala' and '#doOnFirst'.
This will result in showing incorrect example code to users.
```suggestion
: @@snip
[Flow.scala](/docs/src/test/scala/docs/stream/operators/DoOnFirst.scala) {
#imports #doOnFirst }
```
##########
docs/src/main/paradox/stream/operators/Source-or-Flow/doOnFirst.md:
##########
@@ -0,0 +1,31 @@
+# doOnFirst
+
+Run the given function when the first element is received.
+
+@ref[Simple operators](../index.md#simple-operators)
+
+## Signature
+
+@apidoc[Source.doOnFirst](Source) {
scala="#doOnFirst(f:Out=>Unit):FlowOps.this.Repr[Out]"
java="#map(org.apache.pekko.japi.function.Procedure)" }
+@apidoc[Flow.doOnFirst](Flow) {
scala="#doOnFirst(f:Out=>Unit):FlowOps.this.Repr[Out]"
java="#map(org.apache.pekko.japi.function.Procedure)" }
Review Comment:
The Java API documentation links point to '#map' instead of '#doOnFirst'.
This will link to the wrong method in the API documentation, misleading users
about the correct method signature.
```suggestion
@apidoc[Source.doOnFirst](Source) {
scala="#doOnFirst(f:Out=>Unit):FlowOps.this.Repr[Out]"
java="#doOnFirst(org.apache.pekko.japi.function.Procedure)" }
@apidoc[Flow.doOnFirst](Flow) {
scala="#doOnFirst(f:Out=>Unit):FlowOps.this.Repr[Out]"
java="#doOnFirst(org.apache.pekko.japi.function.Procedure)" }
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
