Improve the API examples

crates/koto/examples/args.rs

@@ -2,7 +2,7 @@ fn main() {
     let script = "
 if (size koto.args) > 0
   for i, arg in koto.args.enumerate()
-    print '${i + 1}: $arg'
+    print '{i + 1}: {arg}'
 else
   print 'No arguments'
 ";

crates/koto/examples/rust_object.rs

@@ -7,10 +7,15 @@ print foo.get()
 print foo.set 99
 ";
     let mut koto = Koto::default();
+
     koto.prelude().add_fn("make_foo", |ctx| match ctx.args() {
-        [KValue::Number(n)] => Ok(Foo(n.into()).into()),
+        [KValue::Number(n)] => {
+            let result = Foo::new(*n);
+            Ok(KObject::from(result).into())
+        }
         unexpected => type_error_with_slice("a number", unexpected),
     });
+
     koto.compile_and_run(script).unwrap();
 }
 
@@ -20,6 +25,10 @@ struct Foo(i64);
 // koto_impl generates Koto functions for any function tagged with #[koto_method]
 #[koto_impl]
 impl Foo {
+    fn new(n: KNumber) -> Self {
+        Self(n.into())
+    }
+
     // A simple getter function
     #[koto_method]
     fn get(&self) -> Result<KValue> {
@@ -45,9 +54,3 @@ impl KotoObject for Foo {
         Ok(())
     }
 }
-
-impl From<Foo> for KValue {
-    fn from(x: Foo) -> Self {
-        KObject::from(x).into()
-    }
-}

docs/api.md

@@ -16,36 +16,40 @@ To run a Koto script, instantiate `koto::Koto` and call `compile_and_run`:
 hello_world.rs
 ```
 
-## Passing Arguments to Koto
+## Getting a Return Value
+
+The result of calling `compile_and_run` is a `KValue`, which is Koto's main
+value type.
+
+`KValue` is an enum that contains variants for each of the core Koto types, 
+like `Number`, `String`, etc.
+
+The type of a `KValue` as a string can be retrieved via `KValue::type_as_string`,
+and to render a `KValue`, call `Koto::value_to_string`.
 
 ```rust_include
-args.rs
+return_value.rs
 ```
 
 ## Adding Values to the Prelude
 
 The runtime's prelude is a `KMap`, which is Koto's standard hashmap type. 
 
-Values can be added via `KMap::insert`, taking any value that implements
+can be added via `KMap::insert`, taking any value that implements
 `Into<KValue>`. Basic types like strings and numbers are automatically converted
 to corresponding Koto types. 
 
 ```rust_include
 prelude_value.rs
 ```
 
-## Getting a Return Value
-
-The result of calling `compile_and_run` is a _Koto value_, aka `KValue`.
-
-`KValue` is an enum that contains variants for each of the core Koto value
-types, like `Number`, `String`, etc.
+## Passing Arguments to Koto
 
-The type of a `KValue` as a string can be retrieved via `KValue::type_as_string`,
-and to render a `KValue`, call `Koto::value_to_string`.
+The arguments that are accessible in a script from `koto.args` can be set via
+`Koto::set_args`.
 
 ```rust_include
-return_value.rs
+args.rs
 ```
 
 ## Rust Functions in Koto
@@ -60,16 +64,18 @@ rust_function.rs
 ## Adding a Module to the Prelude
 
 
-A module in Koto is simply a `KMap`, conventionally with a defined `@type`,
-which contains a collection of useful functionality.
+A module in Koto is simply a `KMap`, conventionally with a defined `@type`.
+The `KMap::with_type` initializer sets up an empty map with a `@type` entry.
 
 ```rust_include
 module.rs
 ```
 
 ## Adding a Custom Object Type
 
-Rust types that implement `KotoObject` can be used in the Koto runtime.
+Any Rust type that implements `KotoObject` can be used in the Koto runtime.
+`KotoObject` requires `KotoType`, `KotoCopy`, and `KotoEntries` to be
+implemented. Macros are available to help get everything set up.
 
 ```rust_include
 rust_object.rs