raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

Use apidoc directive in common/binary-compatibility-rules.md (#22904) (#30899)

Browse source
This commit is contained in:
Andrei Arlou 2021-11-18 13:15:08 +02:00 • committed by GitHub
parent bcc9c66237
commit a8c67fc2e6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 4 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

8
akka-docs/src/main/paradox/common/binary-compatibility-rules.md
View file

@ -135,7 +135,7 @@ to change at any time (even if best-effort is taken to keep them compatible).
When browsing the source code and/or looking for methods available to be called, especially from Java which does not
have as rich of an access protection system as Scala has, you may sometimes find methods or classes annotated with
the `/** INTERNAL API */` comment or the `@akka.annotation.InternalApi` annotation.
the `/** INTERNAL API */` comment or the @javadoc[@InternalApi](akka.annotation.InternalApi) annotation.
No compatibility guarantees are given about these classes. They may change or even disappear in minor versions,
and user code is not supposed to call them.
@ -151,11 +151,11 @@ into Internal APIs, as they are subject to change without any warning.
In addition to the special internal API marker two annotations exist in Akka and specifically address the following use cases:
* `@ApiMayChange` – which marks APIs which are known to be not fully stable yet. Read more in @ref:[Modules marked "May Change"](may-change.md)
* `@DoNotInherit` – which marks APIs that are designed under a closed-world assumption, and thus must not be
* @javadoc[@ApiMayChange](akka.annotation.ApiMayChange) – which marks APIs which are known to be not fully stable yet. Read more in @ref:[Modules marked "May Change"](may-change.md)
* @javadoc[@DoNotInherit](akka.annotation.DoNotInherit) – which marks APIs that are designed under a closed-world assumption, and thus must not be
extended outside Akka itself (or such code will risk facing binary incompatibilities). E.g. an interface may be
marked using this annotation, and while the type is public, it is not meant for extension by user-code. This allows
adding new methods to these interfaces without risking to break client code. Examples of such API are the `FlowOps`
adding new methods to these interfaces without risking to break client code. Examples of such API are the @scaladoc[FlowOps](akka.stream.scaladsl.FlowOps)
trait or the Akka HTTP domain model.
Please note that a best-effort approach is always taken when having to change APIs and breakage is avoided as much as