[NICE FIRST CONTRIB] Additional examples for Stream operator docs

[raboof]

Many operators in the stream operator documentation section at https://doc.akka.io/docs/akka/current/stream/operators/index.html do not yet have code examples. Adding such a code example is a great contribution.

Examples of operators that does have example code are:
https://doc.akka.io/docs/akka/current/stream/operators/Source-or-Flow/log.html https://doc.akka.io/docs/akka/current/stream/operators/ActorFlow/ask.html .

Example code in Akka is included in the source tree and is compiled (and thus typechecked) on every build. Sometimes the examples even come from unit tests, so they are not only compiled but even ran and validated. If you can add or find a test that can be used as documentation that is great, otherwise the code can be added to the akka-docs subproject.

To add an example:

• check that nobody claimed the operator in this issue yet
• comment in this issue to 'claim' an operator
• Add (or find) example code, mark it as a Paradox snippet (with //#xxx comments)
• Add a snippet to the markdown file of your operator to include that snippet

Operators

Source operators

• Operator docs: examples for asSource/FlowWithContext #29822 asSourceWithContext
• Document asSubscriber stage #28128 asSubscriber
• Operator docs for Source.combine #28195 combine
• Add source.completionStage example #25468 #28338 completionStage
• Adds example to Source.completionStageSource #28639 completionStageSource
• empty (maybe not needed)
• failed (maybe not needed)
• Example for Source.fromIterator #25468 #28582 fromIterator
• Add docs and examples for RS fromPublisher #28694 fromPublisher
• Adds example to Source.completionStageSource #28639 futureSource
• lazyCompletionStage
• lazyCompletionStageSource
• lazyFuture
• lazyFutureSource
• lazySingle
• lazySource
• Docs: Source.repeat (and friends) #28615 repeat
• Operator docs for Source.tick #28225 tick
• Source.unfold examples #28081 unfold
• Example for Source.unfoldAsync #28111 unfoldAsync
• Example for unfoldResourceAsync #28080 unfoldResourceAsync
• Examples for Source.zipN and Source.zipWithN  #28510 zipN
• Examples for Source.zipN and Source.zipWithN  #28510 zipWithN

Sink operators

• actorRef
• Add Sink.asPublisher example and update doc #30105 asPublisher
• cancelled @muskan3006
• combine
• completionStageSink
• collection
• Adding example of fold for sink #29613 fold
• Docs: Sink.foreach #28693 foreach
• foreachAsync
• foreachParallel
• fromMaterializer
• fromSubscriber
• futureSink
• add example for Sink.head #28782 head
• Adding example of headOption operator #29717 headOption
• Doc example of Sink.ignore, #25468 #28753 ignore
• last
• lastOption
• lazyCompletionStageSink
• lazyFutureSink
• lazySink
• onComplete @mariojaros
• preMaterialize
• queue
• Docs: Reduce operator #29641 reduce
• Docs: sink seq operator examples #28616 seq

Converters

• asInputStream @nitikagarw
• Docs: Example on the as/fromJavaStream operators #28745 asJavaStream
• asOutputStream @nitikagarw
• Docs: examples for io streams with StreamConverters #28746 fromInputStream
• Docs: Example on the as/fromJavaStream operators #28745 fromJavaStream
• Docs: examples for io streams with StreamConverters #28746 fromOutputStream
• javaCollector
• javaCollectorParallelUnordered

Simple operators

• Operator docs: examples for asSource/FlowWithContext #29822 asFlowWithContext
• detach
• Docs #25468 : add code examples for drop and dropWhile Operators #28613 drop
• Docs #25468 : add code examples for drop and dropWhile Operators #28613 dropWhile
• doc: filter and filterNot streams operator, #25468 #28238 filter
• doc: filter and filterNot streams operator, #25468 #28238 filterNot
• doc: Flow.fold #27850 fold
• foldAsync
• fromMaterializer
• futureFlow (in addition to the prefixAndTail example present)
• grouped @chbatey
• intersperse @chbatey
• lazyCompletionStageFlow
• lazyFlow
• lazyFutureFlow
• Limit and LimitWeighted operator docs #28394 limit
• Limit and LimitWeighted operator docs #28394 limitWeighted
• map (change order of example and semantics, add details about throwing/supervision?)
• mapConcat @chbatey
• mapError
• reduce
• @chbatey scanAsync
• Examples for the sliding operator  #28482 sliding
• @johanandren statefulMapConcat
• =doc: take and takeWhile #28078 take
• =doc: take and takeWhile #28078 takeWhile
• Adds throttle example #29203 throttle
• Doc example of Streams watch operator, #25468 #28752 watch

Flow operators composed of Sinks and Sources

• fromSinkAndSource @johanandren
• fromSinkAndSourceCoupled @johanandren

Asynchronous operators

• Docs: sync and refresh ask stream operators #28762 ask
• mapAsync @ignasi35
• mapAsyncUnordered @ignasi35

Timer driven operators

• delay
• dropWithin
• groupedWeightedWithin
• groupedWithin
• initialDelay
• takeWithin

Backpressure aware operators

• batch
• batchWeighted
• buffer
• expand
• extrapolate

Nesting and flattening operators

• flatMapConcat @chbatey
• flatMapMerge @chbatey
• groupBy
• prefixAndTail
• doc: example for splitWhen and splitAfter, #25468 #28480 splitAfter
• doc: example for splitWhen and splitAfter, #25468 #28480 splitWhen

Time aware operators

• backpressureTimeout
• Add completion timeout example #29673 completionTimeout
• idleTimeout
• initialTimeout
• keepAlive

Fan-in operators

• mergeLatest @chbatey
• mergePreferred @JoelWee
• mergePrioritized @JoelWee
• zipLatest
• zipLatestWith

Fan-out operators

• Balance
• doc: Broadcast Stream operator, #25468 #28091 Broadcast
• doc: Partition Streams operator, #25468 #28090 Partition
• Unzip
• UnzipWith
• alsoTo
• divertTo
• wireTap

Watching status operators

• Adds sample code for the monitor operator #29356 monitor
• watchTermination

Actor interop operators

• Docs: sync and refresh ask stream operators #28762 ActorFlow.ask
• ActorSink.actorRef
• ActorSource.actorRefWithBackpressure

Compression operators

• Compression.gzip (reuse the example in Compression.gunzip)
• Compression.gunzip
• Compression.deflate (reuse the example in Compression.inflate)
• Compression.inflate

Error handling

• RestartSource.onFailuresWithBackoff Doc onFailureWithBackoff #28356
• RestartFlow.onFailuresWithBackoff
• RestartSource.withBackoff
• RestartFlow.withBackoff
• RestartSink.withBackoff

[patriknw]

I agree, this is an excellent community ticket and we really need the help to complete all of it.

[salehkhazaei]

I'll do the Fan-in operators. Have little time this week, might take a while :)