docs: fix outdated content and wrong config keys and API names

[pjfanning]

Motivation

A review of the docs found statements that are out of date for Pekko 2.0 (JDK 8 advice, removed features described as current, old build tool versions and syntax, deprecated APIs presented as the main approach) and config keys, class names and method names that do not exist and would fail if copied.

Modification

Outdated for 2.0

• split-brain-resolver.md: auto-down described as removed, not as an opt-in feature
• cluster-usage.md: pekko-cluster script "may be removed in a future release"; explain where jmxsh-R5.jar comes from (the script downloads it); JDK 17 JMX link
• io-dns.md: async-dns "may become the default in a future release"
• common/binary-compatibility-rules.md, common/may-change.md: removed 1.1.0 / Java 8 wording
• additional/deploying.md: replace the removed UseCGroupMemoryLimitForHeap flag with container-support / MaxRAMPercentage guidance
• additional/packaging.md: sbt 1.13.0, com.github.sbt sbt-native-packager 1.13.0, maven-shade 3.6.2, heading matches content; Gradle snippets moved to com.gradleup.shadow 9.6.1 (rewritten because the old Kotlin snippet no longer compiles against Shadow 9 — not tried in a Gradle build, reviewers familiar with Shadow please check)
• project/immutable.md: Lombok 1.18.48 (1.18.10 does not run on JDK 16+)
• general/configuration.md: lightbend/config links; JDK 17 REPL banner
• dispatchers.md, typed/dispatchers.md: drop "Java 9+" qualifier; JDK 17 javadoc links
• multi-jvm-testing.md, multi-node-testing.md: sbt slash syntax, Scala 3 compatible main, JDK 17/21 paths
• persistence.md, persistence-plugins.md: LevelDB 0.12, document both native and Java-port dependencies
• remoting.md: Props.create; supervision-classic.md: no Akka version, whenTerminated; testing.md: Pekko not Akka 2.x
• io-udp.md: drop SecurityManager note; coordinated-shutdown.md: drop pre-fork issue link; distributed-pub-sub.md: drop dead Activator link
• discovery/index.md: remove the "Migrating from Pekko Management Discovery (before 1.0.0)" section (no such pre-1.0 release existed)
• fault-tolerance.md: Java text matches Duration.ofMinutes snippet
• typed/cluster-sharding.md: drop -2.3 flag from the remove-internal-data example; typed/actors.md: correct Java pattern matching versions
• stream docs: MaterializedMap, flatMap note and mapConcat signatures (IterableOnce / java.lang.Iterable), stale "stub" notes, SI-2712/Dotty text, Source.queue prose rewritten for BoundedSourceQueue (deprecated overloads moved to a note), PubSub.source/sink headings, TestSink()/TestSource() instead of removed probe, Source.actorRef completion via completionMatcher, Sink.collection uses scala.collection.Factory, ActorFlow ask timeout is java.util.concurrent.TimeoutException, real description for javaCollectorParallelUnordered

Wrong config keys

• persistence-plugins.md: auto-start-journals / auto-start-snapshot-stores take config paths
• remoting.md: pekko.remote.classic.retry-gate-closed-for; multi-jvm-testing.md: pekko.remote.artery.canonical.port and a real multi-jvm test name
• typed/cluster.md: pekko.cluster.failure-detector.implementation-class, new Down(address)
• remoting-artery.md: pekko.remote.artery.advanced.aeron.aeron-dir
• cluster-client.md, cluster-metrics.md: pekko.actor.provider, fully qualified extension class names
• typed/cluster-concepts.md: monitored by up to 9 nodes; typed/persistence.md: stash-capacity default 4096 and overflow strategy
• additional/operations.md: JMX MBean pekko:type=Cluster
• stream/operators/Source-or-Flow/mapWithResource.md, stream/operators/StreamConverters/fromOutputStream.md: pekko.stream.materializer.blocking-io-dispatcher (no org.apache. prefix); these operators are a Flow and a Sink, not a Source

Wrong API names

• ProducerController, ShardRegion.CurrentShardRegionState, extractShardId, BackoffOnStopOptions/BackoffOnFailureOptions, Replicator.DeleteFailure/StoreFailure, no RefreshInterval hint, org.apache.pekko.actor.typed.ActorSystem, pekko-cluster-typed artifact for singleton, Pekko Projections has its own version, Compression.inflate, RunnableGraph.fromGraph / BidiFlow in stream composition

Other wrong facts

• remoting.md: classic remoting needs netty-transport + netty-handler (not the Netty 3 netty artifact)
• cluster-metrics.md: moving average is set by pekko.cluster.metrics.collector.moving-average-half-life
• routing.md: fork-join-executor; split-brain-resolver.md: stable-after, keep-majority described above
• logging.md: dead letter logging during shutdown is off by default; persistence-schema-evolution.md: Java serialization is disabled by default
• fsm.md: UnsubscribeTransitionCallBack; testing.md: ignoreNoMsg, int, duplicated sentence removed
• persistence-query.md: getReadJournalFor, Offset, newer events, title, ReadJournalProvider label; io-udp.md: Udp.Bind
• includes/cluster.md: remembered entities; discovery/index.md: _service._tcp.pekko.test; general/addressing.md: root down
• project/downstream-upgrade-strategy.md: patch example 1.1.1; common/circuitbreaker.md: not an actor, CompletionStage
• typed/dispatchers.md: org.apache.pekko.dispatch.ExecutorServiceConfigurator; ExtensionDocSpec.scala snippet (used by typed/extending.md): real DatabasePool class name
• typed/guide/tutorial_1.md: typed tell takes one argument; typed/durable-state/persistence.md: DurableStateBehavior names, state not events
• typed/mailboxes.md: fromConfig selects a mailbox, classic ActorSystem.Settings; typed/routers.md: preferLocalRoutees only for group routers
• typed/interaction-patterns.md: typed TimerScheduler links and startTimer* names, askWithStatus links ActorContext, Java StatusReply.ack() link uses StatusReply#ack()
• stream/operators/StreamConverters/fromOutputStream.md: the IOResult carries the number of bytes written, not a file size; typed/replicated-eventsourcing-auction.md: WinnerDecided, Finish

Each change was checked against the source, reference.conf or build files in this repo.

Not included (source changes, can follow separately): the Scaladoc of RemoveInternalClusterShardingData still documents -2.3, the Cluster.scala warning still says "auto-down has been removed in Akka 2.6.0", and the Sink.collection Scaladoc still mentions CanBuildFrom.

Result

The docs match the 2.0 code, and copied config keys and API names work.

Tests

• Not run - docs only (plus a string literal in the ExtensionDocSpec.scala doc snippet)

References

None - found during a review of the docs

[He-Pin]

Impressive work - I independently checked the config keys and API names against reference.conf and the sources and they all hold: pekko.remote.classic.retry-gate-closed-for, pekko.cluster.split-brain-resolver.stable-after, monitored-by-nr-of-members = 9, fork-join-executor (there is no fork-join-dispatcher anywhere), allow-java-serialization = off, and redeliveryBurstLimit. CI is fully green and the @@@ block balance is unchanged in every file.

Two things before I merge:

1. One inline comment below about -2.3.
2. Non-blocking nit: in the ActorFlow ask* pages, replacing @apidoc[AskTimeoutException] with plain java.util.concurrent.TimeoutException is true but less precise - AskTimeoutException is the class actually thrown (ActorFlow.scala:51 catches it, and it extends concurrent.TimeoutException). Keeping a @apidoc[AskTimeoutException] (a java.util.concurrent.TimeoutException) would preserve both the link and the catchable type users need for onErrorResume.

[He-Pin]

-2.3 is not a wrong value here: the flag is still parsed (RemoveInternalClusterShardingData.scala:77 args(0) == "-2.3") and remove2dot3Data is still a parameter of the public remove method. #3584 removes the matching paragraph from the class Scaladoc in the same batch, so if both land the flag ends up documented nowhere while still being live API. Could you keep it in this example (marked as legacy/optional if you like), and let the actual removal be one deliberate change covering code, Scaladoc, docs and MiMa together?

[He-Pin]

Pushed a549820 to restore -2.3 in the RemoveInternalClusterShardingData example - same reasoning as #3584: the flag is still live, so the docs should keep showing it until it is actually removed. Everything else in this PR checked out against the sources. Will merge once CI is green.

[He-Pin]

Also merged current main into the branch (clean, no conflicts) and folded in two small follow-ups from the #3587/#3588 reviews: the malformed @scaladoc[Array](scala.Array)[@scaladoc[Byte](scala.Byte)] nesting in io.md is now the standard @scaladoc[Array[Byte]](scala.Array) form, and the last remaining "observed-removed" typo (typed/distributed-data.md:316) is fixed. Closing #3599/#3600 in favour of keeping these here.

[He-Pin]

Replaced my earlier merge commit with a clean rebase onto current main (8a012b9): your 5 commits replayed without conflicts, plus two small follow-up commits (keep -2.3 in the example; fix the malformed Array[Byte] scaladoc link in io.md and the leftover "observed-removed" typo folded in from #3599/#3600, which are closed). Branch tip is now e3d0f75.

[He-Pin]

lgtm