akka/akka-core

[NICE FIRST CONTRIB] Additional examples for Stream operator docs

Open

#25,468 opened on Aug 13, 2018

View on GitHub
 (35 comments) (0 reactions) (0 assignees)Scala (3,547 forks)batch import
1 - triagedgood first issuehackathonhelp wantedt:docst:stream

Repository metrics

Stars
 (13,277 stars)
PR merge metrics
 (Avg merge 8d 19h) (10 merged PRs in 30d)

Description

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

  • #29822 asSourceWithContext
  • #28128 asSubscriber
  • #28195 combine
  • #28338 completionStage
  • #28639 completionStageSource
  • empty (maybe not needed)
  • failed (maybe not needed)
  • #28582 fromIterator
  • #28694 fromPublisher
  • #28639 futureSource
  • lazyCompletionStage
  • lazyCompletionStageSource
  • lazyFuture
  • lazyFutureSource
  • lazySingle
  • lazySource
  • #28615 repeat
  • #28225 tick
  • #28081 unfold
  • #28111 unfoldAsync
  • #28080 unfoldResourceAsync
  • #28510 zipN
  • #28510 zipWithN

Sink operators

  • actorRef
  • #30105 asPublisher
  • cancelled @muskan3006
  • combine
  • completionStageSink
  • collection
  • #29613 fold
  • #28693 foreach
  • foreachAsync
  • foreachParallel
  • fromMaterializer
  • fromSubscriber
  • futureSink
  • #28782 head
  • #29717 headOption
  • #28753 ignore
  • last
  • lastOption
  • lazyCompletionStageSink
  • lazyFutureSink
  • lazySink
  • onComplete @mariojaros
  • preMaterialize
  • queue
  • #29641 reduce
  • #28616 seq

Converters

  • asInputStream @nitikagarw
  • #28745 asJavaStream
  • asOutputStream @nitikagarw
  • #28746 fromInputStream
  • #28745 fromJavaStream
  • #28746 fromOutputStream
  • javaCollector
  • javaCollectorParallelUnordered

Simple operators

  • #29822 asFlowWithContext
  • detach
  • #28613 drop
  • #28613 dropWhile
  • https://github.com/akka/akka/pull/28238 filter
  • https://github.com/akka/akka/pull/28238 filterNot
  • #27850 fold
  • foldAsync
  • fromMaterializer
  • futureFlow (in addition to the prefixAndTail example present)
  • grouped @chbatey
  • intersperse @chbatey
  • lazyCompletionStageFlow
  • lazyFlow
  • lazyFutureFlow
  • #28394 limit
  • #28394 limitWeighted
  • map (change order of example and semantics, add details about throwing/supervision?)
  • mapConcat @chbatey
  • mapError
  • reduce
  • @chbatey scanAsync
  • #28482 sliding
  • @johanandren statefulMapConcat
  • #28078 take
  • #28078 takeWhile
  • #29203 throttle
  • #28752 watch

Flow operators composed of Sinks and Sources

  • fromSinkAndSource @johanandren
  • fromSinkAndSourceCoupled @johanandren

Asynchronous 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

Time aware operators

  • backpressureTimeout
  • #29673 completionTimeout
  • idleTimeout
  • initialTimeout
  • keepAlive

Fan-in operators

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

Fan-out operators

  • Balance
  • #28091 Broadcast
  • #28090 Partition
  • Unzip
  • UnzipWith
  • alsoTo
  • divertTo
  • wireTap

Watching status operators

  • #29356 monitor
  • watchTermination

Actor interop 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

Contributor guide

Research direction
Pick an unclaimed operator from the list, comment to claim it, then add a code snippet following the instructions in the issue.
Tech stack
scala
Domain
backend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
ScalaGitAkka
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80