Update binary API and inlining example

Author: nicolasstucki

content/binary-api.md

@@ -121,29 +121,35 @@ In the bytecode, `@binaryAPIAccessor` generated accessors will have the [ACC_PUB
 
 #### Binary API and inlining
 
-If there is a reference to a binary API in an inline method we can use the definition without needing an inline accessor.
+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 `@binaryAPIAccessor` the accessor is used;
+ - otherwise, an accessor is automatically generated and used. We will emit a warning with an actionable diagnostic containing the code needed to migrate to `@binaryAPI` or `@binaryAPIAccessor`.
 
 Example 3:
 ~~~ scala
 class C {
-  @binaryAPI protected def a: Int = ...
-  protected def b: Int = ...
-  inline def foo: Int = a + b
+  @binaryAPIAccessor private def a: Int = ...
+  private def b: Int = ...
+  @binaryAPI 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 protected def a: Int = ...
-  protected def b: Int = ...
-  final def C$inline$b: Int = ...
-  inline def foo: Int = a + C$inline$b
+  @binaryAPIAccessor private def a: Int = ...
+  private def b: Int = ...
+  @binaryAPI protected def c: Int = ...
+  protected def d: Int = ...
+  final def C$inline$a: Int = ... // generated by `@binaryAPIAccessor`
+  final def C$inline$b: Int = ... // warn: `b` should be annotated with `@binaryAPIAccessor` + migration code
+  final def C$inline$d: Int = ... // warn: `d` should be annotated with `@binaryAPI` + migration code
+  inline def foo: Int = C$inline$a + C$inline$b + c + C$inline$d
 }
 ~~~
 
-Note that if the inlined member is `a` would be private, we would generate the accessor `C$inline$a`, which happens to be binary compatible with the automatically generated one.
-This is only a tiny mitigation of binary compatibility issues compared with all the different ways accessors can be generated.
-
 ### Specification
 
 We must add `binaryAPI` and `binaryAPIAccessor` to the standard library.