Add docs and a tests demonstrating how not to use the fakes

fixtures/coverall/tests/bindings/test_coverall.kts

@@ -7,8 +7,6 @@ import java.util.concurrent.*
 
 import uniffi.coverall.*
 
-import com.sun.jna.Pointer
-
 // TODO: use an actual test runner.
 
 // Test some_dict().
@@ -446,3 +444,24 @@ FakeCoveralls("using_fakes").use { coveralls ->
     coveralls.addPatch(patch)
     assert(!coveralls.getRepairs().isEmpty())
 }
+
+FakeCoveralls("using_fakes_and_calling_methods_without_override_crashes").use { coveralls ->
+    var exception: Throwable? = null
+    try {
+        coveralls.cloneMe()
+    } catch (e: Throwable) {
+        exception = e
+    }
+    assert(exception != null)
+}
+
+Coveralls("using_fakes_with_real_objects_crashes").use { coveralls ->
+    val patch = FakePatch(Color.RED)
+    var exception: Throwable? = null
+    try {
+        coveralls.addPatch(patch)
+    } catch (e: Throwable) {
+        exception = e
+    }
+    assert(exception != null)
+}

uniffi_bindgen/src/bindings/kotlin/templates/ObjectRuntime.kt

@@ -117,8 +117,16 @@ abstract class FFIObject: Disposable, AutoCloseable {
         this.pointer = pointer
     }
 
+    /**
+     * This constructor can be used to instantiate a fake object.
+     *
+     * **WARNING: Any object instantiated with this constructor cannot be passed to an actual Rust-backed object.**
+     * Since there isn't a backing [Pointer] the FFI lower functions will crash.
+     * @param noPointer Placeholder value so we can have a constructor separate from the default empty one that may be
+     *   implemented for classes extending [FFIObject].
+     */
     @Suppress("UNUSED_PARAMETER")
-    protected constructor(noPointer: NoPointer) {
+    constructor(noPointer: NoPointer) {
         this.pointer = null
     }
 
@@ -171,4 +179,5 @@ abstract class FFIObject: Disposable, AutoCloseable {
     }
 }
 
+/** Used to instantiate a [FFIObject] without an actual pointer, for fakes in tests, mostly. */
 object NoPointer

uniffi_bindgen/src/bindings/kotlin/templates/ObjectTemplate.kt

@@ -7,7 +7,15 @@ open class {{ impl_class_name }} : FFIObject{% if obj.is_trait_interface() %}, {
 
     constructor(pointer: Pointer): super(pointer)
 
-    protected constructor(noPointer: NoPointer): super(noPointer)
+    /**
+     * This constructor can be used to instantiate a fake object.
+     *
+     * **WARNING: Any object instantiated with this constructor cannot be passed to an actual Rust-backed object.**
+     * Since there isn't a backing [Pointer] the FFI lower functions will crash.
+     * @param noPointer Placeholder value so we can have a constructor separate from the default empty one that may be
+     *   implemented for classes extending [FFIObject].
+     */
+    constructor(noPointer: NoPointer): super(noPointer)
 
     {%- match obj.primary_constructor() %}
     {%- when Some with (cons) %}