Skip to content

docs: fix broken links, anchors and snippet labels - #3587

Merged
He-Pin merged 2 commits into
apache:mainfrom
pjfanning:docs-fix-broken-links
Oct 9, 2026
Merged

docs: fix broken links, anchors and snippet labels#3587
He-Pin merged 2 commits into
apache:mainfrom
pjfanning:docs-fix-broken-links

Conversation

@pjfanning

@pjfanning pjfanning commented Oct 8, 2026

Copy link
Copy Markdown
Member

Motivation

A review of the docs found links that point to the wrong class, file or
anchor, API doc anchors that do not match the actual signatures,
snippet labels that name the wrong file, and invalid directives
(@api, @apiref, @apidoc).

Modification

  • actors.md: classic ReceiveBuilder target, actor-hotswap and
    actor-reply anchors, fully qualified Future anchors, Timer snippet
    labels
  • cluster-client.md: AbstractActor#getSender() target, sample link text
  • event-bus.md: EventBus.scala github path, javadoc for LookupEventBus
  • futures.md: scala.concurrent.Future; io-tcp.md: jdocs/io/japi path
  • coordination.md, general/jmm.md: snippet labels
  • serialization.md: stray quote in URL
  • additional/rolling-updates.md: released pekko-management extref,
    @ref to the SBR strategies section
  • typed/: Receptionist.Listing target, supervise anchor, snippet and
    tab labels, thenRun and StatusReply.ack anchors, @apidoc instead of
    @api/@apiref/@apidoc
  • stream/: async, pull and SourceRef targets; operator page anchors and
    labels for Sink.never/source, flattenOptional, PubSub.sink/source,
    fromOutputStream, alsoToAll, interleaveAll, concatLazy, dropRepeated,
    groupedAdjacentByWeighted, mapAsyncPartitioned(Unordered),
    mapWithResource, materializeIntoSource, monitor, onErrorContinue,
    prepend/prependLazy, preMaterialize, takeUntil, watchTermination,
    mapConcat/statefulMapConcat, ActorSink.actorRef

Notes for review:

Result

Links and API doc anchors point to existing targets and labels match
the referenced files.

Tests

  • Not run - docs only

References

None - found during a review of the docs

@pjfanning
docs: fix broken links, anchors and snippet labels
0cb4ff6 
Motivation:
A review of the docs found links that point to the wrong class, file or
anchor, API doc anchors that do not match the actual signatures,
snippet labels that name the wrong file, and invalid directives
(@api, @apiref, @apidoc).

Modification:
- actors.md: classic ReceiveBuilder target, actor-hotswap and
  actor-reply anchors, fully qualified Future anchors, Timer snippet
  labels
- cluster-client.md: AbstractActor#getSender() target, sample link text
- event-bus.md: EventBus.scala github path, javadoc for LookupEventBus
- futures.md: scala.concurrent.Future; io-tcp.md: jdocs/io/japi path
- coordination.md, general/jmm.md: snippet labels
- serialization.md: stray quote in URL
- additional/rolling-updates.md: released pekko-management extref,
  @ref to the SBR strategies section
- typed/: Receptionist.Listing target, supervise anchor, snippet and
  tab labels, thenRun and StatusReply.ack anchors, @apidoc instead of
  @api/@apiref/@apidoc
- stream/: async, pull and SourceRef targets; operator page anchors and
  labels for Sink.never/source, flattenOptional, PubSub.sink/source,
  fromOutputStream, alsoToAll, interleaveAll, concatLazy, dropRepeated,
  groupedAdjacentByWeighted, mapAsyncPartitioned(Unordered),
  mapWithResource, materializeIntoSource, monitor, onErrorContinue,
  prepend/prependLazy, preMaterialize, takeUntil, watchTermination,
  mapConcat/statefulMapConcat, ActorSink.actorRef

Result:
Links and API doc anchors point to existing targets and labels match
the referenced files.

Tests:
- Not run - docs only

References:
None - found during a review of the docs
pjfanning added a commit to pjfanning/incubator-pekko that referenced this pull request Oct 8, 2026
@pjfanning
docs: fix StatusReply.ack javadoc anchor and fromOutputStream result
c42d3a4 
Motivation:
Two fixes were held back from apache#3587 because they touch files this PR
also changes.

Modification:
- typed/interaction-patterns.md: the Java StatusReply.ack() link used a
  Scaladoc-style StatusReply$ target; use pekko.pattern.StatusReply#ack()
- StreamConverters/fromOutputStream.md: the IOResult carries the number
  of bytes written, not the size of a file (OutputStreamGraphStage)

Result:
The link resolves and the description matches the code.

Tests:
- Not run - docs only

References:
Refs apache#3587
@pjfanning pjfanning mentioned this pull request Oct 8, 2026
Merged
@pjfanning
docs: remove duplicated note on the prepend operator page
f3f21c5 
Motivation:
prepend.md has the same note twice; the first copy is indented, so it
renders as a code block. apache#3588 skipped it because this PR changes a
line inside it.

Modification:
Remove the indented copy and keep the second note.

Result:
The note appears once and renders as a note.

Tests:
- Not run - docs only

References:
Refs apache#3588
@pjfanning pjfanning mentioned this pull request Oct 8, 2026
Merged
@pjfanning pjfanning added this to the 2.0.0-M5 milestone Oct 8, 2026
He-Pin
He-Pin approved these changes Oct 9, 2026
View reviewed changes

@He-Pin He-Pin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@He-Pin
He-Pin merged commit 6bddca4 into apache:main Oct 9, 2026
10 checks passed
This was referenced Oct 9, 2026
Closed
Merged
He-Pin pushed a commit to pjfanning/incubator-pekko that referenced this pull request Oct 9, 2026
@pjfanning @He-Pin
docs: fix StatusReply.ack javadoc anchor and fromOutputStream result
dd09330 
Motivation:
Two fixes were held back from apache#3587 because they touch files this PR
also changes.

Modification:
- typed/interaction-patterns.md: the Java StatusReply.ack() link used a
  Scaladoc-style StatusReply$ target; use pekko.pattern.StatusReply#ack()
- StreamConverters/fromOutputStream.md: the IOResult carries the number
  of bytes written, not the size of a file (OutputStreamGraphStage)

Result:
The link resolves and the description matches the code.

Tests:
- Not run - docs only

References:
Refs apache#3587
He-Pin added a commit that referenced this pull request Oct 9, 2026
@pjfanning @He-Pin
docs: fix outdated content and wrong config keys and API names (#3583)
2ca08f4 
* docs: fix outdated content and wrong config keys and API names

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 described as the main way)
and config keys, class names and method names that do not exist and
would fail if copied.

Modification:
- Outdated for 2.0: auto-down, the pekko-cluster script, async-dns
  default, binary compatibility and may-change notes, container JVM
  flags, packaging tool versions and Gradle Shadow snippets, Lombok
  version, typesafehub links, Java 8/9 qualifiers and javadoc links,
  sbt colon/`in` syntax and procedure syntax in multi-jvm testing,
  JDK paths in multi-node testing, LevelDB dependencies, Props.create,
  Akka version references, the SecurityManager UDP note, pre-fork
  issue and Activator links, the pre-1.0 Pekko Management migration
  section, the -2.3 sharding data flag, Java pattern matching
  versions, stream docs (MaterializedMap, flatMap note, mapConcat
  signatures, stubs, SI-2712/Dotty, deprecated Source.queue prose,
  TestSink/TestSource.probe, Source.actorRef completion,
  Sink.collection Factory, ActorFlow timeout exception,
  javaCollectorParallelUnordered description)
- Wrong config keys: auto-start-journals/snapshot-stores values,
  classic retry-gate-closed-for, artery canonical port, failure
  detector implementation-class, aeron-dir, actor.provider, extension
  FQCNs, monitored-by-nr-of-members default, stash-capacity default,
  JMX MBean name
- Wrong API names: ProducerController, CurrentShardRegionState,
  extractShardId, Backoff options, DeleteFailure/StoreFailure,
  RefreshInterval, typed ActorSystem, pekko-cluster-typed artifact,
  Pekko Projections version, Compression.inflate, RunnableGraph and
  BidiFlow in stream composition

Result:
The docs match the 2.0 code and copied config/API names work.

Tests:
- Not run - docs only

References:
None - found during a review of the docs

* docs: fix blocking-io-dispatcher key in mapWithResource and fromOutputStream

Motivation:
The mapWithResource and fromOutputStream operator pages give the
blocking dispatcher setting as
org.apache.pekko.stream.materializer.blocking-io-dispatcher, which does
not exist, and call these operators a Source.

Modification:
Use pekko.stream.materializer.blocking-io-dispatcher, and call them a
Flow and a Sink.

Result:
The documented key matches stream reference.conf.

Tests:
- Not run - docs only

References:
Refs #3586

* docs: fix more wrong facts, settings and API names

Motivation:
More doc pages state facts, settings and API names that do not match
the code.

Modification:
- remoting.md: classic remoting needs netty-transport and netty-handler
- cluster-metrics.md: name moving-average-half-life and link this page
- routing.md: fork-join-executor
- split-brain-resolver.md: stable-after; keep-majority is 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, remove duplicated sentence
- persistence-query.md: getReadJournalFor, Offset, newer events, title,
  ReadJournalProvider label
- io-udp.md: Udp.Bind in Scala
- 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 (typed/extending.md snippet): 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 Settings
- typed/routers.md: preferLocalRoutees is only for group routers
- typed/interaction-patterns.md: typed TimerScheduler links and
  startTimer* names; askWithStatus links ActorContext
- typed/replicated-eventsourcing-auction.md: WinnerDecided, Finish

Result:
These pages match the code.

Tests:
- Not run - docs only (plus a string in a doc snippet source)

References:
None - found during a review of the docs

* docs: fix StatusReply.ack javadoc anchor and fromOutputStream result

Motivation:
Two fixes were held back from #3587 because they touch files this PR
also changes.

Modification:
- typed/interaction-patterns.md: the Java StatusReply.ack() link used a
  Scaladoc-style StatusReply$ target; use pekko.pattern.StatusReply#ack()
- StreamConverters/fromOutputStream.md: the IOResult carries the number
  of bytes written, not the size of a file (OutputStreamGraphStage)

Result:
The link resolves and the description matches the code.

Tests:
- Not run - docs only

References:
Refs #3587

* docs: fix typos next to lines changed in this PR

Motivation:
#3588 fixes typos across the docs but skipped the ones next to lines
this PR changes, to avoid merge conflicts.

Modification:
- split-brain-resolver.md: stray asterisk, "its self" -> "itself"
- discovery/index.md: "which i configured" -> "which is configured",
  "which two hosts" -> "with two hosts"

Result:
These typos are fixed without conflicting with #3588.

Tests:
- Not run - docs only

References:
Refs #3588

* docs: keep -2.3 in the RemoveInternalClusterShardingData example

* docs: fix the broken Array[Byte] scaladoc link and the leftover observed-removed typo

---------

Co-authored-by: 虎鸣 <hepin.p@alibaba-inc.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@He-Pin He-Pin He-Pin approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

2.0.0-M5

Development

Successfully merging this pull request may close these issues.

2 participants

@pjfanning @He-Pin