doc(docs.topics.jvm.javaToKotlinInterop): add notes and examples

docs/topics/jvm/java-to-kotlin-interop/README.md

@@ -5,10 +5,17 @@
 * TODO:
 * static fields
 * static methods
+* TODO:
+* overloads generation
+* TODO:
 
 ## Prerequisites
 * [Install the compiler locally](https://kotlinlang.org/docs/command-line.html#install-the-compiler)
 * Define an environment variable to the kotlin root path installation(`HOMEBREW_KOTLIN_ROOT`)
+* [Download CFR Java decompiler](https://github.com/leibnitz27/cfr)
+  * allows
+    * ".class" -- is decompiled to -- ".java"
+  * place | this path, to use it
 
 ## How to create & run an application?
 * The application will be just 1! `.kt` file
@@ -18,4 +25,10 @@
 * `javac -cp .:$HOMEBREW_KOTLIN_ROOT/lib/kotlin-stdlib.jar JavaToKotlinInterOp.java`
   * create the `JavaToKotlinInterOp.class`
 * `java -cp .:$HOMEBREW_KOTLIN_ROOT/lib/kotlin-stdlib.jar JavaToKotlinInterOp`
-  * run the application
+  * run the application
+
+## How to generate from ".kt" -> ".java"?
+* `kotlinc Circle.kt -d .`
+  * generate "Circle.class"
+* `java -jar cfr-0.152.jar Circle.class`
+  * decompile as output, the "Circle.java"

docs/topics/jvm/java-to-kotlin-interop/java-to-kotlin-interop.md

@@ -354,37 +354,39 @@ var x: Int = 23
 
 ## Overloads generation
 
-Normally, if you write a Kotlin function with default parameter values, it will be visible in Java only as a full
-signature, with all parameters present. If you wish to expose multiple overloads to Java callers, you can use the
-[`@JvmOverloads`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.jvm/-jvm-overloads/index.html) annotation.
-
-The annotation also works for constructors, static methods, and so on. It can't be used on abstract methods, including
-methods defined in interfaces.
-
-```kotlin
-class Circle @JvmOverloads constructor(centerX: Int, centerY: Int, radius: Double = 1.0) {
-    @JvmOverloads fun draw(label: String, lineWidth: Int = 1, color: String = "red") { /*...*/ }
-}
-```
-
-For every parameter with a default value, this will generate one additional overload, which has this parameter and
-all parameters to the right of it in the parameter list removed. In this example, the following will be
-generated:
-
-```java
-// Constructors:
-Circle(int centerX, int centerY, double radius)
-Circle(int centerX, int centerY)
-
-// Methods
-void draw(String label, int lineWidth, String color) { }
-void draw(String label, int lineWidth) { }
-void draw(String label) { }
-```
-
-Note that, as described in [Secondary constructors](classes.md#secondary-constructors), if a class has default
-values for all constructor parameters, a public constructor with no arguments will be generated for it. This works even
-if the `@JvmOverloads` annotation is not specified.
+* [`@JvmOverloads`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.jvm/-jvm-overloads/index.html)
+  * allows
+    * expose MULTIPLE overloads -- to -- Java callers
+      * if Kotlin function / default parameter values -> | Java, visible ONLY as a FULL signature 
+  * uses
+    * | 
+      * constructors,
+      * static methods 
+    * ❌NOT valid | ❌
+      * abstract methods
+      * methods / defined | interfaces
+  * _Example:_ 1 additional overload / EVERY parameter -- with a -- default value
+    ```kotlin
+    class Circle @JvmOverloads constructor(centerX: Int, centerY: Int, radius: Double = 1.0) {
+        @JvmOverloads fun draw(label: String, lineWidth: Int = 1, color: String = "red") { /*...*/ }
+    }
+    ```
+
+    generate
+
+    ```java
+    // Constructors:
+    Circle(int centerX, int centerY, double radius)
+    Circle(int centerX, int centerY)
+
+    // Methods
+    void draw(String label, int lineWidth, String color) { }
+    void draw(String label, int lineWidth) { }
+    void draw(String label) { }
+    ```
+
+  * if a class has default values / ALL constructor parameters & `@JvmOverloads` NOT use it -> it will generate a public constructor / NO arguments
+    * see [Secondary constructors](classes.md#secondary-constructors)
 
 ## Checked exceptions
 

docs/topics/jvm/java-to-kotlin-interop/overloadsGeneration.kt

@@ -0,0 +1,3 @@
+class Circle @JvmOverloads constructor(centerX: Int, centerY: Int, radius: Double = 1.0) {
+    @JvmOverloads fun draw(label: String, lineWidth: Int = 1, color: String = "red") { /*...*/ }
+}