Change name of annotation to @publicInBinary

Author: nicolasstucki

content/binary-api.md

@@ -10,15 +10,16 @@ title: SIP-52 - Binary APIs
 
 ## History
 
-| Date          | Version            |
-|---------------|--------------------|
-| Feb 27 2022   | Initial Draft      |
-| Aug 16 2022   | Single Annotation  |
+| Date          | Version                |
+|---------------|------------------------|
+| Feb 27 2022   | Initial Draft          |
+| Aug 16 2022   | Single Annotation      |
+| Aug 24 2022   | Change Annotation Name |
 
 ## Summary
 
 The purpose of binary APIs is to have publicly accessible definitions in generated bytecode for definitions that are package private or protected.
-This proposal introduces the `@binaryAPI` annotation on term definitions and the `-WunstableInlineAccessors` linting flag.
+This proposal introduces the `@publicInBinary` annotation on term definitions and the `-WunstableInlineAccessors` linting flag.
 
 
 ## Motivation
@@ -68,11 +69,11 @@ object C:
 
 ### High-level overview
 
-This proposal introduces the `@binaryAPI` annotation, and adds a migration path to inline methods in libraries (requiring binary compatibility).
+This proposal introduces the `@publicInBinary` annotation, and adds a migration path to inline methods in libraries (requiring binary compatibility).
 
-#### `@binaryAPI` annotation
+#### `@publicInBinary` annotation
 
-A binary API is a definition that is annotated with `@binaryAPI` or overrides a definition annotated with `@binaryAPI`.
+A binary API is a definition that is annotated with `@publicInBinary` or overrides a definition annotated with `@publicInBinary`.
 This annotation can be placed on `def`, `val`, `lazy val`, `var`, `object`, and `given` definitions.
 A binary API will be publicly available in the bytecode.
 
@@ -84,9 +85,9 @@ Example:
 
 ~~~ scala
 class C {
-  @binaryAPI private[C] def packagePrivateAPI: Int = ...
-  @binaryAPI protected def protectedAPI: Int = ...
-  @binaryAPI def publicAPI: Int = ... // warn: `@binaryAPI` has no effect on public definitions
+  @publicInBinary private[C] def packagePrivateAPI: Int = ...
+  @publicInBinary protected def protectedAPI: Int = ...
+  @publicInBinary def publicAPI: Int = ... // warn: `@publicInBinary` has no effect on public definitions
 }
 ~~~
 will generate the following bytecode signatures
@@ -99,32 +100,32 @@ public class C {
 }
 ~~~
 
-In the bytecode, `@binaryAPI` definitions will have the [ACC_PUBLIC](https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.1-200-E.1) flag.
+In the bytecode, `@publicInBinary` definitions will have the [ACC_PUBLIC](https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.1-200-E.1) flag.
 <!-- We can also set the [ACC_SYNTHETIC](https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.1-200-E.1) to hide these definitions from javac and java IDEs. -->
 
 #### Binary API and inlining
 
 A non-public reference in an inline method is handled as follows:
- - if the reference is a `@binaryAPI` the reference is used;
+ - if the reference is a `@publicInBinary` the reference is used;
  - otherwise, an accessor is automatically generated and used.
 
 Example:
 ~~~ scala
-import scala.annotation.binaryAPI
+import scala.annotation.publicInBinary
 class C {
-  @binaryAPI private[C] def a: Int = ...
+  @publicInBinary private[C] def a: Int = ...
   private[C] def b: Int = ...
-  @binaryAPI protected def c: Int = ...
+  @publicInBinary protected def c: Int = ...
   protected def d: Int = ...
   inline def foo: Int = a + b + c + d
 }
 ~~~
 before inlining the compiler will generate the accessors for inlined definitions
 ~~~ scala
 class C {
-  @binaryAPI private[C] def a: Int = ...
+  @publicInBinary private[C] def a: Int = ...
   private[C] def b: Int = ...
-  @binaryAPI protected def c: Int = ...
+  @publicInBinary protected def c: Int = ...
   protected def d: Int = ...
   final def C$$inline$b: Int = ...
   final def C$$inline$d: Int = ...
@@ -171,15 +172,15 @@ When an accessor is detected we can tell the user how to fix the issue. For exam
   |
   | To make sure that the inlined code is binary compatible you must make sure that
   | method b is public in the binary API.
-  |  * Option 1: Annotate method b with @binaryAPI
+  |  * Option 1: Annotate method b with @publicInBinary
   |  * Option 2: Make method b public
   |
   | This change may break binary compatibility if a previous version of this
   | library was compiled with generated accessors. Binary compatibility should
   | be checked using MiMa. If binary compatibility is broken, you should add the
   | old accessor explicitly in the source code. The following code should be
   | added to class C:
-  |   @binaryAPI private[C] def C$$inline$b: Int = this.b
+  |   @publicInBinary private[C] def C$$inline$b: Int = this.b
    -----------------------------------------------------------------------------
 -- [E...] Compatibility Warning: C.scala -----------------------------
   |  inline def foo: Int = a + b + c + d
@@ -194,55 +195,55 @@ When an accessor is detected we can tell the user how to fix the issue. For exam
   |
   | To make sure that the inlined code is binary compatible you must make sure that
   | method d is public in the binary API.
-  |  * Option 1: Annotate method d with @binaryAPI
+  |  * Option 1: Annotate method d with @publicInBinary
   |  * Option 2: Make method d public
   |
   | This change may break binary compatibility if a previous version of this
   | library was compiled with generated accessors. Binary compatibility should
   | be checked using MiMa. If binary compatibility is broken, you should add the
   | old accessor explicitly in the source code. The following code should be
   | added to class C:
-  |   @binaryAPI private[C] def C$$inline$d: Int = this.d
+  |   @publicInBinary private[C] def C$$inline$d: Int = this.d
    -----------------------------------------------------------------------------
 ~~~
 
 </details>
 
 ### Specification
 
-We must add `binaryAPI` to the standard library.
+We must add `publicInBinary` to the standard library.
 
 ```scala
 package scala.annotation
 
-final class binaryAPI extends scala.annotation.StaticAnnotation
+final class publicInBinary extends scala.annotation.StaticAnnotation
 ```
 
-#### `@binaryAPI` annotation
+#### `@publicInBinary` annotation
 
 * Only valid on `def`, `val`, `lazy val`, `var`, `object`, and `given`.
-* TASTy will contain references to non-public definitions that are out of scope but `@binaryAPI`. TASTy already allows those references.
+* TASTy will contain references to non-public definitions that are out of scope but `@publicInBinary`. TASTy already allows those references.
 * The annotated definitions will be public in the generated bytecode. Definitions should be made public as early as possible in the compiler phases, as this can remove the need to create other accessors. It should be done after we check the accessibility of references.
 
 #### Inline
 
 * Inlining will not require the generation of an inline accessor for binary APIs.
 * The user will be warned if a new inline accessor is automatically generated under `-WunstableInlineAccessors`.
-  The message will suggest `@binaryAPI` and how to fix potential incompatibilities.
+  The message will suggest `@publicInBinary` and how to fix potential incompatibilities.
 
 ### Compatibility
 
-The introduction of the `@binaryAPI` do not introduce any binary incompatibility.
+The introduction of the `@publicInBinary` do not introduce any binary incompatibility.
 
-Using references to `@binaryAPI` in inline code can cause binary incompatibilities. These incompatibilities are equivalent to the ones that can occur due to the unsoundness we want to fix. When migrating to binary APIs, the compiler will show the implementation of accessors that the users need to add to keep binary compatibility with pre-binaryAPI code.
+Using references to `@publicInBinary` in inline code can cause binary incompatibilities. These incompatibilities are equivalent to the ones that can occur due to the unsoundness we want to fix. When migrating to binary APIs, the compiler will show the implementation of accessors that the users need to add to keep binary compatibility with pre-publicInBinary code.
 
 ### Other concerns
 
-* Tools that analyze inlined TASTy code might need to know about `@binaryAPI`. For example [MiMa](https://github.com/lightbend/mima/) and [TASTy MiMa](https://github.com/scalacenter/tasty-mima).
+* Tools that analyze inlined TASTy code might need to know about `@publicInBinary`. For example [MiMa](https://github.com/lightbend/mima/) and [TASTy MiMa](https://github.com/scalacenter/tasty-mima).
 
 ## Alternatives
 
-### Add a `@binaryAPIAccessor`
+### Add a `@binaryAccessor`
 This annotation would generate an stable accessor. This annotation could be used on `private` definition. It would also mitigate [migration costs](https://gist.github.com/nicolasstucki/003f7293941836b08a0d53dbcb913e3c) for library authors that have published unstable accessors.
 
 * Implementation https://github.com/lampepfl/dotty/pull/16992