From 64c27e435baec40f3da3464bd14c7b15a07cd4f6 Mon Sep 17 00:00:00 2001 From: Josep Prat Date: Thu, 10 Dec 2020 15:20:14 +0100 Subject: [PATCH] [Docs] Fix wrong syntax using paradox directives (#29876) * Fix wrong syntax using paradox directives * Simplify collection.md - Only available for Scala, so hide most of the page for Java --- .../src/main/paradox/project/immutable.md | 42 +++++++------------ .../stream/operators/Sink/collection.md | 11 ++--- .../paradox/stream/operators/Source/never.md | 4 +- 3 files changed, 23 insertions(+), 34 deletions(-) diff --git a/akka-docs/src/main/paradox/project/immutable.md b/akka-docs/src/main/paradox/project/immutable.md index 957ef91f31..d37f8ae58f 100644 --- a/akka-docs/src/main/paradox/project/immutable.md +++ b/akka-docs/src/main/paradox/project/immutable.md @@ -3,7 +3,7 @@ project.description: Data immutability using Project Lombok --- # Immutability using Lombok -A preferred best practise in Akka is to have immutable messages. Scala provides case class which makes it extremely easy +A preferred best practice in Akka is to have immutable messages. Scala provides case class which makes it extremely easy to have short and clean classes for creating immutable objects, but no such facility is easily available in Java. We can make use of several third party libraries which help is achieving this. One good example is Lombok. @@ -17,29 +17,17 @@ Lombok handles the following details for you. It: * creates correct `equals`, `hashCode` and a human-friendly `toString` * creates a constructor requiring all fields. - ### Adding Lombok to your project + To add Lombok to a Maven project, declare it as a simple dependency: -Maven -: @@dependency { - - org.projectlombok - lombok - 1.18.10 - +@@dependency[Maven,Gradle] { + group="org.projectlombok" + artifact="lombok" + version=1.18.10 } -Gradle -: @@dependency { - dependencies { - compileOnly 'org.projectlombok:lombok:1.18.10' - annotationProcessor 'org.projectlombok:lombok:1.18.10' - } -} - - -# Using lombok +# Using lombok @Value public class LombokUser { @@ -48,15 +36,15 @@ Gradle String email; } - -The example does not demonstrate other useful Lombok features like `@Builder` or `@Wither` which will help -you create builder and copy methods. Be aware that Lombok is not an immutability library but a -code generation library which means some setups might not create immutable objects. -For example, Lombok’s @Data is equivalent to Lombok’s @Value but will also synthesize mutable methods. + +The example does not demonstrate other useful Lombok features like `@Builder` or `@Wither` which will help +you create builder and copy methods. Be aware that Lombok is not an immutability library but a +code generation library which means some setups might not create immutable objects. +For example, Lombok’s @Data is equivalent to Lombok’s @Value but will also synthesize mutable methods. Don’t use Lombok’s @Data when creating immutable classes. -Using Lombok for creating a message class for actors is quite simple. In following example, Message class -just defines the member variable and Lombok annotation '@Value' takes care of creating methods like +Using Lombok for creating a message class for actors is quite simple. In following example, Message class +just defines the member variable and Lombok annotation '@Value' takes care of creating methods like getter, toString, hashCode, equals. public class MyActor extends AbstractActor { @@ -82,6 +70,8 @@ getter, toString, hashCode, equals. } ### Integrating Lombok with an IDE + Lombok integrates with popular IDEs: + * To use Lombok in IntelliJ IDEA you'll need the [Lombok Plugin for IntelliJ IDEA](https://plugins.jetbrains.com/plugin/6317-lombok) and you'll also need to enable Annotation Processing (`Settings / Build,Execution,Deployment / Compiler / Annotation Processors` and tick `Enable annotation processing`) * To Use Lombok in Eclipse, run `java -jar lombok.jar` (see the video at [Project Lombok](https://projectlombok.org/)). diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/collection.md b/akka-docs/src/main/paradox/stream/operators/Sink/collection.md index 324b319e2e..aa5e39e734 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/collection.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/collection.md @@ -4,14 +4,15 @@ @ref[Sink operators](../index.md#sink-operators) +@@@div { .group-scala } + ## Signature @apidoc[Sink.collection](Sink$) { scala="#collection[T,That](implicitcbf:akka.util.ccompat.Factory[T,Thatwithscala.collection.immutable.Iterable[_]]):akka.stream.scaladsl.Sink[T,scala.concurrent.Future[That]]" } - ## Description -@scala[Collect values emitted from the stream into an arbitrary collection `That`. The resulting collection is available through a `Future[That]` or when the stream completes. Note that the collection boundaries are those defined in the `CanBuildFrom` associated with the chosen collection. See [The Architecture of Scala 2.13's Collections](https://docs.scala-lang.org/overviews/core/architecture-of-scala-213-collections.html) for more info. The [`seq`](seq.html) operator is a shorthand for `Sink.collection[T, Vector[T]]`.]@java[Operator only available in the Scala API. The closest operator in the Java API is [`Sink.seq`](seq.html).] +Collect values emitted from the stream into an arbitrary collection `That`. The resulting collection is available through a `Future[That]` or when the stream completes. Note that the collection boundaries are those defined in the `CanBuildFrom` associated with the chosen collection. See [The Architecture of Scala 2.13's Collections](https://docs.scala-lang.org/overviews/core/architecture-of-scala-213-collections.html) for more info. The [`seq`](seq.html) operator is a shorthand for `Sink.collection[T, Vector[T]]`. ## Example @@ -22,10 +23,10 @@ Scala ## Reactive Streams semantics -@@@ - -@@@div { .group-scala .callout } +@@@@div { .callout } **cancels** If too many values are collected +@@@@ + @@@ diff --git a/akka-docs/src/main/paradox/stream/operators/Source/never.md b/akka-docs/src/main/paradox/stream/operators/Source/never.md index 4b07141417..b3533444a4 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/never.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/never.md @@ -8,9 +8,7 @@ Never emit any elements, never complete and never fail. ## Signature -@@signature [Source.scala](/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #never } - -@@@ +@apidoc[Source.never](Source$) { scala="#never[T]:akka.stream.scaladsl.Source[T,akka.NotUsed]" java="#never()" } ## Description