From 9e366a7cceaf9577c72720a9c9e4225efed81756 Mon Sep 17 00:00:00 2001 From: Lucas Satabin Date: Thu, 19 Sep 2024 10:37:08 +0200 Subject: [PATCH] Fix links to scaladoc Laika adds the `com.commercetools.queue` prefix package to every entity linked via the `@:api` directive. Remove it from every use site. Also fixes links to objects by adding the missing `$` suffix. --- docs/getting-started/administration.md | 2 +- docs/getting-started/publishing.md | 6 +++--- docs/getting-started/serialization.md | 4 ++-- docs/getting-started/stats.md | 4 ++-- docs/getting-started/subscribing.md | 18 +++++++++--------- docs/getting-started/testing.md | 12 ++++++------ docs/integrations/circe.md | 4 ++-- docs/integrations/otel4s.md | 2 +- docs/systems/index.md | 2 +- 9 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/getting-started/administration.md b/docs/getting-started/administration.md index 2e53999..1744ee6 100644 --- a/docs/getting-started/administration.md +++ b/docs/getting-started/administration.md @@ -1,7 +1,7 @@ {% nav = true %} # Managing Queues -Managing queues is made using the @:api(com.commercetools.queue.QueueAdministration). You can acquire an instance through a @:api(com.commercetools.queue.QueueClient) by using the `administration()` method. A `QueueAdministration` instance is **not** associated to any specific queue. The queue to operate on will be provided in each administration method. +Managing queues is made using the @:api(QueueAdministration). You can acquire an instance through a @:api(QueueClient) by using the `administration()` method. A `QueueAdministration` instance is **not** associated to any specific queue. The queue to operate on will be provided in each administration method. ```scala mdoc import cats.effect.IO diff --git a/docs/getting-started/publishing.md b/docs/getting-started/publishing.md index 1f267ea..40a4d81 100644 --- a/docs/getting-started/publishing.md +++ b/docs/getting-started/publishing.md @@ -1,7 +1,7 @@ {% nav = true %} # Publishing Data -Publishing data is made using a @:api(com.commercetools.queue.QueuePublisher). You can acquire one through a @:api(com.commercetools.queue.QueueClient) by using the `publish()` method. A `QueuePublisher` is associated to a specific queue, which is provided when creating the publisher. +Publishing data is made using a @:api(QueuePublisher). You can acquire one through a @:api(QueueClient) by using the `publish()` method. A `QueuePublisher` is associated to a specific queue, which is provided when creating the publisher. The publisher also requires a [data serializer][doc-serializer] upon creation for the type of data you want to publish to it. @@ -20,7 +20,7 @@ def publisher: QueuePublisher[IO, String] = ## Pipe a stream through the publisher sink -The @:api(com.commercetools.queue.QueuePublisher) abstraction provides a `sink()` pipe, through which you can make your publishing source stream go. +The @:api(QueuePublisher) abstraction provides a `sink()` pipe, through which you can make your publishing source stream go. The pipe takes a parameter allowing for batching publications. ```scala mdoc:compile-only @@ -41,7 +41,7 @@ Several `Stream`s can safely publish to the same sink concurrently, so you can r ## Explicit publish -If you are integrating the library with an existing code base that performs explicit publications to the queue, you can access the @:api(com.commercetools.queue.QueuePusher) lower level API, which exposes ways to publish a single message or a single batch. +If you are integrating the library with an existing code base that performs explicit publications to the queue, you can access the @:api(QueuePusher) lower level API, which exposes ways to publish a single message or a single batch. This abstraction comes in handy when the messages you produce do not come from a `Stream`, otherwise you should prefer the `sink()` pipe presented above. A `QueuePusher` is accessed as a [`Resource`][cats-effect-resource] as it usually implies using a connection pool. When the resource is released, the pools will be disposed properly. diff --git a/docs/getting-started/serialization.md b/docs/getting-started/serialization.md index 3fbb098..0acdf49 100644 --- a/docs/getting-started/serialization.md +++ b/docs/getting-started/serialization.md @@ -6,7 +6,7 @@ The proper string encoding/decoding is performed by the underlying SDK, allowing ## Data `Serializer` -A @:api(com.commercetools.queue.Serializer) is defined as a _SAM interface_ that is basically a `T => String`. Defining a new one can be done easily by providing an implicit conversion function from the type `T` to serialize to a `String`. +A @:api(Serializer) is defined as a _SAM interface_ that is basically a `T => String`. Defining a new one can be done easily by providing an implicit conversion function from the type `T` to serialize to a `String`. For instance, adding a serializer for `Int`s can be done as follows. @@ -20,7 +20,7 @@ The library provides natively a _no-op_ serializer for `String`s. ## Data `Deserializer` -A @:api(com.commercetools.queue.Deserializer) is defined as a _SAM interface_ that is basically a `String => Either[Throwable, T]`. Defining a new one can be done easily by providing an implicit conversion function from a `String` to serialize to either a value of the type `T` or an exception. +A @:api(Deserializer) is defined as a _SAM interface_ that is basically a `String => Either[Throwable, T]`. Defining a new one can be done easily by providing an implicit conversion function from a `String` to serialize to either a value of the type `T` or an exception. For instance, adding a deserializer for `Int`s can be done as follows. diff --git a/docs/getting-started/stats.md b/docs/getting-started/stats.md index d1f27a6..222d9e0 100644 --- a/docs/getting-started/stats.md +++ b/docs/getting-started/stats.md @@ -1,7 +1,7 @@ {% nav = true %} # Queue Statistics -The library exposes a simple interface to access basic queue statistics through a @:api(com.commercetools.queue.QueueStatistics). +The library exposes a simple interface to access basic queue statistics through a @:api(QueueStatistics). @:callout(warning) The numbers reported by the statistics are approximate numbers. Depending on the underlying system, there might be some delay in data availability. @@ -41,7 +41,7 @@ If you want the stream to fail upon the first fetching error, you can use the `s ## Explicit fetch -If you are integrating this library with an existing code base that performs explicit fetches for queue statistics, you can access the @:api(com.commercetools.queue.QueueStatsFetcher) lower level API, which exposes a way to fetch statistics explicitly. +If you are integrating this library with an existing code base that performs explicit fetches for queue statistics, you can access the @:api(QueueStatsFetcher) lower level API, which exposes a way to fetch statistics explicitly. A `QueueStatsFetcher` is accessed as a [`Resource`][cats-effect-resource] as it usually implies using a connection pool. When the resource is released, the pools will be disposed properly. diff --git a/docs/getting-started/subscribing.md b/docs/getting-started/subscribing.md index b06fb64..0ff25f5 100644 --- a/docs/getting-started/subscribing.md +++ b/docs/getting-started/subscribing.md @@ -1,7 +1,7 @@ {% nav = true %} # Receiving Data -Receiving data is achieved through a @:api(com.commercetools.queue.QueueSubscriber). You can acquire one throuh a @:api(com.commercetools.queue.QueueClient) by using the `subscribe()` method. A `QueueSubscriber` is associated with a specific queue, which is provided when creating the subscriber. +Receiving data is achieved through a @:api(QueueSubscriber). You can acquire one throuh a @:api(QueueClient) by using the `subscribe()` method. A `QueueSubscriber` is associated with a specific queue, which is provided when creating the subscriber. The subscriber also requires a [data deserializer][doc-deserializer] upon creation, to deserialize the message payload received from the queue. @@ -30,7 +30,7 @@ In the following, we explain what kind of control flow handling is provided by t ## Processors -The @:api(com.commercetools.queue.QueueSubscriber) abstraction provides a `processWithAutoAck()` method, which automatically handles the control flow part for you. You only need to provide the processing function, allowing you to focus on your business logic. +The @:api(QueueSubscriber) abstraction provides a `processWithAutoAck()` method, which automatically handles the control flow part for you. You only need to provide the processing function, allowing you to focus on your business logic. @:callout(info) The `payload` is effectful as it performs data deserialization, which can fail when a message payload is malformed. @@ -47,7 +47,7 @@ subscriber.processWithAutoAck(batchSize = 10, waitingTime = 20.seconds) { messag } ``` -The processing function receives a @:api(com.commercetools.queue.Message), which gives access to the content and some metadata of the received messages. +The processing function receives a @:api(Message), which gives access to the content and some metadata of the received messages. The result is a `Stream` of the processing results, emitted in the order the messages where received. Only the successfully processed messages are emitted down-stream. The stream is failed upon the first failed processing. @@ -56,10 +56,10 @@ The `processWithAutoAck` method performs automatic acking/nacking for you depend If you wish to implement a stream that does not fail upon error, you can use the `attemptProcessWithAutoAck()` methods, which emits the results of the processing as an `Either[Throwable, T]`. The resulting stream does not fail if some processing fails. Otherwise it has the same behavior as the stream above. For more flexibility in terms of what to do with each received messages, you can also check `process()` and `processWithImmediateDecision()`, -that will give access to the content and some metadata of the received messages, apply some effects and return a @:api(com.commercetools.queue.Decision), -to dictate whether each message should be confirmed (see @:api(com.commercetools.queue.Decision.Ok)), dropped (see @:api(com.commercetools.queue.Decision.Drop), -considered as failed (see @:api(com.commercetools.queue.Decision.Fail)), or if the message should be re-enqueued (see @:api(com.commercetools.queue.Decision.Reenqueue)). -An @:api(com.commercetools.queue.ImmediateDecision) is a kind of decision that won't allow messages to get re-enqueued. +that will give access to the content and some metadata of the received messages, apply some effects and return a @:api(Decision), +to dictate whether each message should be confirmed (see @:api(Decision.Ok)), dropped (see @:api(Decision.Drop), +considered as failed (see @:api(Decision.Fail)), or if the message should be re-enqueued (see @:api(Decision.Reenqueue)). +An @:api(ImmediateDecision) is a kind of decision that won't allow messages to get re-enqueued. These variants of processors can be as involved as needed, and allow to cover a wide range of use cases, declaratively. @@ -95,7 +95,7 @@ subscriber.process[Int]( ## Raw message stream If you want more fine-grained tuning of the control flow part, you can resort to the `messages()` stream available via the `QueueSubscriber`. -The stream emits a @:api(com.commercetools.queue.MessageContext) for each received message, giving access to the message content and metadata, as well as to message control methods. +The stream emits a @:api(MessageContext) for each received message, giving access to the message content and metadata, as well as to message control methods. Using this stream, you can implement your processing strategy. @@ -142,7 +142,7 @@ There are three different methods that can be used to control the message lifecy ## Explicit pull -If you are integrating this library with an existing code base that performs explicit pulls from the queue, you can access the @:api(com.commercetools.queue.QueuePuller) lower level API, which exposes ways to pull batch of messages. +If you are integrating this library with an existing code base that performs explicit pulls from the queue, you can access the @:api(QueuePuller) lower level API, which exposes ways to pull batch of messages. This abstraction comes in handy when your processing code is based on a callback approach and is not implemented as a `Stream`, otherwise you should prefer the streams presented above. A `QueuePuller` is accessed as a [`Resource`][cats-effect-resource] as it usually implies using a connection pool. When the resource is released, the pools will be disposed properly. diff --git a/docs/getting-started/testing.md b/docs/getting-started/testing.md index cad1d34..1269aea 100644 --- a/docs/getting-started/testing.md +++ b/docs/getting-started/testing.md @@ -9,12 +9,12 @@ libraryDependencies += "com.commercetools" %% "fs2-queues-testing" % "@VERSION@" ## Using `TestQueue` -The @:api(com.commercetools.queue.testing.TestQueue) class implements an in-memory queue system. A `TestQueue` can be wrapped to create a: +The @:api(testing.TestQueue) class implements an in-memory queue system. A `TestQueue` can be wrapped to create a: - - puller via @:api(com.commercetools.queue.testing.TestQueuePuller) `apply` method - - pusher via @:api(com.commercetools.queue.testing.TestQueuePusher) `apply` method - - subscriber via @:api(com.commercetools.queue.testing.TestQueueSubscriber) `apply` method - - publisher via @:api(com.commercetools.queue.testing.TestQueuePublisher) `apply` method + - puller via @:api(testing.TestQueuePuller$) `apply` method + - pusher via @:api(testing.TestQueuePusher$) `apply` method + - subscriber via @:api(testing.TestQueueSubscriber$) `apply` method + - publisher via @:api(testing.TestQueuePublisher$) `apply` method The `TestQueue` and the various test tools are designed to work well when used with the [cats-effect test runtime][test-runtime] @@ -63,7 +63,7 @@ These variants are available on test entities. ## Testing message contexts -If you need to unit test different behavior on message contexts, you can use the @:api(com.commercetools.queue.testing.TestingMessageContext) class. +If you need to unit test different behavior on message contexts, you can use the @:api(testing.TestingMessageContext) class. It allows you to create a message context with different behaviors. For instance, if you want to check the behavior of a failing ack on a message, you can use this approach: diff --git a/docs/integrations/circe.md b/docs/integrations/circe.md index 8b623b1..4b35db6 100644 --- a/docs/integrations/circe.md +++ b/docs/integrations/circe.md @@ -8,8 +8,8 @@ libraryDependencies += "com.commercetools" %% "fs2-queues-circe" % "@VERSION@" It provides: - - a @:api(com.commercetools.queue.Serializer) for each type `T` that has an implicit `io.circe.Encoder[T]` in scope. - - a @:api(com.commercetools.queue.Deserializer) for each type `T` that has an implicit `io.circe.Decoder[T]` in scope. + - a @:api(Serializer) for each type `T` that has an implicit `io.circe.Encoder[T]` in scope. + - a @:api(Deserializer) for each type `T` that has an implicit `io.circe.Decoder[T]` in scope. To get this feature in your code base, import the following: diff --git a/docs/integrations/otel4s.md b/docs/integrations/otel4s.md index f4240a2..94e172a 100644 --- a/docs/integrations/otel4s.md +++ b/docs/integrations/otel4s.md @@ -6,7 +6,7 @@ The otel4s provides an integration with the [otel4s][otel4s] library. libraryDependencies += "com.commercetools" %% "fs2-queues-otel4s" % "@VERSION@" ``` -It allows you to wrap an existing @:api(com.commercetools.queue.QueueClient) into a @:api(com.commercetools.queue.otel4s.MeasuringQueueClient), which adds [tracing][otel4s-tracing] and [metrics][otel4s-metrics] on every call to the underlying queue system. +It allows you to wrap an existing @:api(QueueClient) into a @:api(otel4s.MeasuringQueueClient$), which adds [tracing][otel4s-tracing] and [metrics][otel4s-metrics] on every call to the underlying queue system. You can opt-in for either one of them or both. diff --git a/docs/systems/index.md b/docs/systems/index.md index fefcfdf..326fe35 100644 --- a/docs/systems/index.md +++ b/docs/systems/index.md @@ -1,5 +1,5 @@ # Providers -`fs2-queues` comes with several queue system implementations. Each of them implements the @:api(com.commercetools.queue.QueueClient) abstraction with the various interfaces it gives access to. +`fs2-queues` comes with several queue system implementations. Each of them implements the @:api(QueueClient) abstraction with the various interfaces it gives access to. Each implementations comes with its own way to get access to a client, depending on the underlying SDK. Please have a look at the provider documentation to see the different ways to instantiate the clients.