Spec for native declarations

spec-docs/jvm-native-flag-support.md

@@ -0,0 +1,59 @@
+# Support for JVM's ACC_NATIVE flag
+
+Goal: enable JNI interop for Kotlin, so that anything that works through JNI in Java could be reproduced 1-to-1 in Kotlin
+
+## Syntax
+
+The following definition is present in the library:
+
+``` kotlin
+package kotlin.jvm
+
+Retention(RetentionPolicy.SOURCE)
+public annotation class native
+```
+
+This annotation is applicable to
+ - functions
+ - property accessors
+
+A declaration marked with this annotation is referred to as a *native declaration*.
+
+Checks to perform:
+ - a native declaration can not be abstract
+ - a native declaration can not have a body
+ - a native declaration can not be marked `inline`
+ - a native declaration can not have `reified` type parameters
+   NOTE: this is achieved through prohibiting `inline`, as `reified` is only allowed on inline-functions now
+ - members of traits can not be native
+
+NOTE: native members can override open (or abstract) members of supertypes
+
+## Semantics on the JVM
+
+Intuition: a JVM method whose source declaration is native is marked with the `ACC_NATIVE` flag, and has no `CODE` attribute.
+
+### Interaction with \[platformStatic\]
+
+A native member of an object marked `native` and `platformStatic` is translated in a straightforward way:
+there is only one JVM method corresponding to it, and it is marked as `ACC_NATIVE`.
+
+A member of a class object of class `C` marked `native` and `platformStatic` yields two JVM methods:
+ - static member of `C` that is marked `ACC_NATIVE`;
+ - instance member of `C$object` that is not marked `ACC_NATIVE` and its body delegates to the native static method.
+
+### Top-level declarations
+
+A native member of package `p` yields one JVM method:
+ - member of a package-facade class `PPackage` which is marked with `ACC_NATIVE` flag.
+
+### Native Property Accessors
+
+A property can not be marked `native`.
+A *property accessor* can be marked `native`. In this case the generated code is the same as for a native function defined in the same
+context as the property.
+
+## Not implemented (yet)
+
+- native property accessors
+- applicability checks: only functions and property accessors