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

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

@@ -18,5 +18,22 @@ public static void main(String[] args) {
         // 2.2 static field's visibility -- via lateinit -- == property setter's visibility
         // TODO: Comprehend it
         Singleton.provider = new Provider(); // public static non-final field in Singleton class
+
+        // 3. package-level function
+        new org.example.Util();
+        org.example.PackageLevelFunctionsKt.getTime();    // package-level function -> static
+        // TODO:
+
+        // 4. static methods
+        // 4.1 @JvmStatic | companion object's function
+        C.callStatic();     // mark it with @JvmStatic -> static function works
+        //C.callNonStatic();  // error: NOT a static method
+        C.Companion.callStatic();    // via Companion == object -> valid
+        C.Companion.callNonStatic(); // via Companion == object -> valid
+        // 4.2 @JvmStatic | named object's function
+        Obj.callStatic();       // mark it with @JvmStatic -> static function works
+        //Obj.callNonStatic();  // error: NOT a static method
+        Obj.INSTANCE.callNonStatic(); // via instance -> valid
+        Obj.INSTANCE.callStatic();    // via instance -> valid
     }
 }

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

@@ -1,16 +1,20 @@
 # Goal
 * instances of a Kotlin class -- can be seamlessly -- created and operated | ".java"
 * TODO:
+* package-level functions
+* TODO:
 * static fields
+* static methods
 
 ## 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`)
 
 ## How to create & run an application?
 * The application will be just 1! `.kt` file
-* `kotlinc Person.kt StaticFields.kt -d .`
+* `kotlinc Person.kt StaticFields.kt packageLevelFunctions.kt StaticMethods.kt -d .`
   * create the `Person.class` & `Key...class`
+  * check 'org/example' folder has been created / contains ".class"
 * `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`

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

@@ -0,0 +1,13 @@
+// 1. @JvmStatic | companion object's function
+class C {
+    companion object {
+        @JvmStatic fun callStatic() {}
+        fun callNonStatic() {}  // THIS one is NOT marked with @JvmStatic
+    }
+}
+
+// 2. @JvmStatic | named object's function
+object Obj {
+    @JvmStatic fun callStatic() {}
+    fun callNonStatic() {}      // THIS one is NOT marked with @JvmStatic
+}

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

@@ -34,25 +34,10 @@ This rule applies for properties of any type, not just `Boolean`.
 
 ## Package-level functions
 
-All the functions and properties declared in a file `app.kt` inside a package `org.example`, including extension functions,
-are compiled into static methods of a Java class named `org.example.AppKt`.
+* 👁️ ALL the functions (also extension) & properties | package `packageName` | file `fileName.kt` -- are compiled into -- static methods | `packageName.FileNameKt.class` (Java class) 👁️
 
-```kotlin
-// app.kt
-package org.example
-
-class Util
-
-fun getTime() { /*...*/ }
-
-```
-
-```java
-// Java
-new org.example.Util();
-org.example.AppKt.getTime();
-```
 
+* TODO:
 To set a custom name to the generated Java class, use the `@JvmName` annotation:
 
 ```kotlin
@@ -174,49 +159,12 @@ int version = C.VERSION;
 
 ## Static methods
 
-As mentioned above, Kotlin represents package-level functions as static methods.
-Kotlin can also generate static methods for functions defined in named objects or companion objects if you annotate those
-functions as [`@JvmStatic`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.jvm/-jvm-static/index.html).
-If you use this annotation, the compiler will generate both a static method in the enclosing class of the object and
-an instance method in the object itself. For example:
+* if you add [`@JvmStatic`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.jvm/-jvm-static/index.html) | functions in named objects OR companion objects -- generate -> 
+  * static method | enclosing class of the object & 
+  * instance method | object itself
 
-```kotlin
-class C {
-    companion object {
-        @JvmStatic fun callStatic() {}
-        fun callNonStatic() {}
-    }
-}
-```
-
-Now, `callStatic()` is static in Java while `callNonStatic()` is not:
-
-```java
-
-C.callStatic(); // works fine
-C.callNonStatic(); // error: not a static method
-C.Companion.callStatic(); // instance method remains
-C.Companion.callNonStatic(); // the only way it works
-```
-
-Same for named objects:
-
-```kotlin
-object Obj {
-    @JvmStatic fun callStatic() {}
-    fun callNonStatic() {}
-}
-```
-
-In Java:
 
-```java
-
-Obj.callStatic(); // works fine
-Obj.callNonStatic(); // error
-Obj.INSTANCE.callNonStatic(); // works, a call through the singleton instance
-Obj.INSTANCE.callStatic(); // works too
-```
+* TODO:
 
 Starting from Kotlin 1.3, `@JvmStatic` applies to functions defined in companion objects of interfaces as well.
 Such functions compile to static methods in interfaces. Note that static method in interfaces were introduced in Java 1.8,

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

@@ -0,0 +1,8 @@
+package org.example
+
+class Util
+
+// package-level function
+fun getTime() {
+    println("getTime()")
+}