Scaladoc generation fix (evolution-gaming#840)

* Fix Scaladoc generation failures in persistence-kafka

The doc task (run by +publish) failed on 5 broken Scaladoc references
introduced with the transactional snapshot docs:

- [[ScheduleCommit]] could not be linked (imported type, not a linkable
  member) -> use a monospace reference.
- s"$groupId-$inputTopic" was parsed as Scaladoc variable expansions
  ($groupId, $inputTopic undefined) -> reword without interpolation.
- [[caching]] was ambiguous between the two caching overloads -> de-link
  to a monospace reference.
- [[cachingTransactional]] from the trait scope could not be resolved
  -> reference it via the companion object name.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011rniFrCMdoVACjj6CVd8xB

* CI: validate Scaladoc generation on PRs

Scaladoc was only generated by '+publish' at release time, so broken
doc links/references could merge to master and only surface as a failed
release. Add a 'Compile/doc' step to the CI test job (both Scala 2.13
and 3.3 matrix legs) so they fail the PR instead.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011rniFrCMdoVACjj6CVd8xB

* Apply scalafmt to reformatted doc comments

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011rniFrCMdoVACjj6CVd8xB

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: tobiajo

.github/workflows/ci.yml

@@ -41,6 +41,10 @@ jobs:
       if: success()
       run: sbt clean coverage "++${{ matrix.scala }} test" docs/mdoc "++${{ matrix.scala }} versionPolicyCheck"
 
+    - name: Check Scaladoc ${{ matrix.scala }} # Scaladoc is only generated by `+publish` at release time; validate it here so broken links/refs fail the PR instead of slipping to master
+      if: success()
+      run: sbt "++${{ matrix.scala }} Compile/doc"
+
     - name: Report test coverage
       if: success() && github.repository == 'evolution-gaming/kafka-flow'
       env:

persistence-kafka/src/main/scala/com/evolutiongaming/kafka/flow/kafkapersistence/KafkaPersistenceModule.scala

@@ -28,7 +28,7 @@ trait KafkaPersistenceModule[F[_], S] {
 
   /** A `ScheduleCommit` that overrides the default way input offsets are committed (by the consumer), binding them to
     * the snapshot writes for single-writer offset safety. `None` means the module does not override it and offsets are
-    * committed the default way. See [[cachingTransactional]].
+    * committed the default way. See `KafkaPersistenceModule.cachingTransactional`.
     */
   def scheduleCommit: Option[ScheduleCommit[F]]
 }
@@ -44,7 +44,7 @@ object KafkaPersistenceModule {
     *   `clientId` is suffixed with it
     * @param transactionalIdPrefix
     *   prefix for `transactional.id` (partition number and a unique per-producer suffix are appended). Fencing is by
-    *   consumer generation, not this id, so it is just a readable label; `s"$groupId-$inputTopic"` is fine.
+    *   consumer generation, not this id, so it is just a readable label (e.g. a `"<groupId>-<inputTopic>"` string).
     * @param snapshotTopic
     *   snapshot topic name (should be configured as a 'compacted' topic) to read/write snapshots
     * @param inputTopic
@@ -156,14 +156,14 @@ object KafkaPersistenceModule {
     }
   }
 
-  /** Variant of [[caching]] protecting the snapshot topic from stale writers by binding the input-offset commit into
-    * the snapshot transaction. Each assigned partition gets a transactional producer with a unique `transactional.id`;
+  /** Variant of `caching` protecting the snapshot topic from stale writers by binding the input-offset commit into the
+    * snapshot transaction. Each assigned partition gets a transactional producer with a unique `transactional.id`;
     * snapshot writes run in group-committed transactions (see [[KafkaSnapshotWriteDatabase.transactional]]) that also
     * commit the input offset. A stale consumer generation is rejected by the broker (KIP-447), aborting the
     * transaction, so a stale owner can neither advance offsets nor overwrite a newer snapshot. Recovery reads with
-    * `read_committed`, and unlike [[caching]] the identity partition mapping is always used; output stays
-    * at-least-once. See the "Protecting against stale snapshot writes" persistence docs for guarantees, limitations,
-    * costs and rollout, and `docs/kafka-single-writer-design.md` for the mechanism.
+    * `read_committed`, and unlike `caching` the identity partition mapping is always used; output stays at-least-once.
+    * See the "Protecting against stale snapshot writes" persistence docs for guarantees, limitations, costs and
+    * rollout, and `docs/kafka-single-writer-design.md` for the mechanism.
     */
   def cachingTransactional[F[_]: LogOf: Async: Parallel: Runtime, S](
     consumerOf: ConsumerOf[F],

persistence-kafka/src/main/scala/com/evolutiongaming/kafka/flow/kafkapersistence/KafkaSnapshotWriteDatabase.scala

@@ -23,8 +23,8 @@ object KafkaSnapshotWriteDatabase {
   ): SnapshotWriteDatabase[F, KafkaKey, S] =
     apply(snapshotTopicPartition, partitionMapper, record => producer.send(record).flatten.void)
 
-  /** Result of [[transactional]]: the snapshot write database plus a [[ScheduleCommit]] that routes input offset
-    * commits through the same per-partition transactions as the snapshot writes.
+  /** Result of [[transactional]]: the snapshot write database plus a `ScheduleCommit` that routes input offset commits
+    * through the same per-partition transactions as the snapshot writes.
     */
   final case class Transactional[F[_], S](
     writeDatabase: SnapshotWriteDatabase[F, KafkaKey, S],