From bc43c63c6bfc1365cad9b990e035454184360fe9 Mon Sep 17 00:00:00 2001
From: Mattia Iavarone <mattia@deepmedia.io>
Date: Sun, 8 Sep 2024 18:41:47 +0200
Subject: [PATCH] Object docs

---
 docs/features/index.mdx   |  1 +
 docs/features/objects.mdx | 52 +++++++++++++++++++++++++++++++++++++++
 docs/index.mdx            |  4 +--
 3 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 docs/features/objects.mdx

diff --git a/docs/features/index.mdx b/docs/features/index.mdx
index bb99fa5..80a43eb 100644
--- a/docs/features/index.mdx
+++ b/docs/features/index.mdx
@@ -10,6 +10,7 @@ docs:
   - builtin-types
   - enums
   - classes
+  - objects
   - interfaces
   - buffers
 ---
diff --git a/docs/features/objects.mdx b/docs/features/objects.mdx
new file mode 100644
index 0000000..5b35a0a
--- /dev/null
+++ b/docs/features/objects.mdx
@@ -0,0 +1,52 @@
+---
+title: Objects
+description: >
+  Understand how Knee compiler plugin can serialize declared objects and let you pass them from Kotlin Native
+  to the JVM and vice versa, including support for externally defined objects.
+---
+
+# Objects
+
+## Annotating objects
+
+Whenever you declare an object, you can use the `@KneeObject` annotation to tell the compiler that it should be processed.
+Knee supports objects in different scenarios:
+
+- top level objects
+- objects nested inside another declaration
+- `companion` objects
+
+```kotlin
+@KneeObject object Foo {
+    ...
+}
+
+class Utilities {
+    @KneeObject object Bar { ... }
+    @KneeObject companion object { ... }
+}
+```
+
+Under the hood, objects are *not* actually serialized and passed through the JNI interface: since there can only be a single
+instance of an object, no extra information is needed and the compiler can retrieve the object field statically on both
+platforms.
+
+## Annotating members
+
+All callable members (functions, properties, constructors) of an object can be made available to the JVM side, but
+they must be explicitly marked with the `@Knee` annotation as described in the [callables](callables) documentation.
+
+```kotlin
+@KneeObject object Game {
+    @Knee fun start() { ... }
+    fun loop() { ... }
+}
+```
+
+In the example above, only the `start` function will be available on the JVM side.
+
+## Importing objects
+
+If you wish to annotate existing objects that you don't control, for example those coming from a different module,
+you can technically use `@KneeObject` on type aliases. Unfortunately as of now, this functionality is very limited in that you
+can't choose which declarations will be imported.
\ No newline at end of file
diff --git a/docs/index.mdx b/docs/index.mdx
index a9390b6..c826a70 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -28,7 +28,7 @@ where you'll learn about all supported features such as:
 - [Exception support](features/exceptions), including custom exception types
 - Built-in serialization of [language primitives](features/builtin-types#primitives): numbers, strings, nullables, `Unit`, `Nothing`
 - Built-in serialization of [collection types](features/builtin-types#collections): lists, sets, efficient arrays
-- Custom [enums](features/enums) and [classes](features/classes)
-- Custom [interfaces](features/interfaces) for two-way invocations
+- Serialization of [enums](features/enums), [classes](features/classes) and [objects](features/objects)
+- Serialization of [interfaces](features/interfaces) for two-way invocations
 - Lambdas and [generics](features/interfaces#importing-interfaces) support
 - [No-copy buffers](features/buffers), mapping `java.nio` buffers to `CPointer` on native