Improve type conversion doc

See #28

Author: ubolonton

guide/src/type-conversions.md

@@ -4,8 +4,6 @@ The type `Value` represents Lisp values:
 - They can be copied around, but cannot outlive the `Env` they come from.
 - They are "proxy values": only useful when converted to Rust values, or used as arguments when calling Lisp functions.
 
-Lisp vectors are represented by the type `Vector`, which can be considered a "sub-type" of `Value`.
-
 ## Converting a Lisp `Value` to Rust
 
 This is enabled for types that implement `FromLisp`. Most built-in types are supported. Note that conversion may fail, so the return type is `Result<T>`.
@@ -18,12 +16,7 @@ let s = value.into_rust::<String>()?;
 let s: Option<&str> = value.into_rust()?; // None if Lisp value is nil
 ```
 
-By default, no utf-8 validation is done when converting strings. This can be enabled through a feature:
-
-```toml
-[dependencies.emacs]
-features = ["utf-8-validation"]
-```
+It's better to declare input types for `#[defun]` than calling `.into_rust()`, unless delayed conversion is needed.
 
 ## Converting a Rust Value to Lisp
 
@@ -41,7 +34,9 @@ true.into_lisp(env)?; // t
 false.into_lisp(env)?; // nil
 ```
 
-## Integer Conversion
+It's better to declare return type for `#[defun]` than calling `.into_lisp(env)`, whenever possible.
+
+## Integers
 
 Integer conversion is lossless by default, which means that a module will signal an "out of range" `rust-error` in cases such as:
 - A `#[defun]` expecting `u8` gets passed `-1`.
@@ -53,3 +48,26 @@ To disable this behavior, use the `lossy-integer-conversion` feature:
 [dependencies.emacs]
 features = ["lossy-integer-conversion"]
 ```
+
+## Strings
+
+By default, no utf-8 validation is done when converting Lisp strings into Rust strings, because the string data returned by Emacs is guaranteed to be valid utf-8 sequence. If you think you've otherwise encountered an Emacs bug, utf-8 validation can be enabled through a feature:
+
+```toml
+[dependencies.emacs]
+features = ["utf-8-validation"]
+```
+
+## Vectors
+
+Lisp vectors are represented by the type `Vector`, which can be considered a "sub-type" of `Value`.
+
+To construct Lisp vectors, use `env.make_vector` and `env.vector`, which are efficient wrappers of Emacs's built-in subroutines `make-vector` and `vector`.
+
+```rust
+env.make_vector(5, ())?;
+
+env.vector([1, 2, 3])?;
+
+env.vector((1, "x", true))?;
+```