dynamic: add some doc comments

wezterm-dynamic/src/error.rs

@@ -3,6 +3,7 @@ use crate::value::Value;
 use thiserror::Error;
 
 #[derive(Error, Debug)]
+#[non_exhaustive]
 pub enum Error {
     #[error("`{}` is not a valid {} variant. {}", .variant_name, .type_name, Self::possible_matches(.variant_name, &.possible))]
     InvalidVariantForType {

wezterm-dynamic/src/fromdynamic.rs

@@ -5,10 +5,15 @@ use std::collections::HashMap;
 use std::convert::TryInto;
 use std::hash::Hash;
 
+/// Specify how FromDynamic will treat unknown fields
+/// when converting from Value to a given target type
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum UnknownFieldAction {
+    /// Don't check, don't warn, don't raise an error
     Ignore,
+    /// Emit a log::warn log
     Warn,
+    /// Return an Error
     Deny,
 }
 
@@ -18,6 +23,7 @@ impl Default for UnknownFieldAction {
     }
 }
 
+/// Specify various options for FromDynamic::from_dynamic
 #[derive(Copy, Clone, Debug, Default)]
 pub struct FromDynamicOptions {
     pub unknown_fields: UnknownFieldAction,
@@ -32,6 +38,8 @@ impl FromDynamicOptions {
     }
 }
 
+/// The FromDynamic trait allows a type to construct itself from a Value.
+/// This trait can be derived.
 pub trait FromDynamic {
     fn from_dynamic(value: &Value, options: FromDynamicOptions) -> Result<Self, Error>
     where

wezterm-dynamic/src/todynamic.rs

@@ -3,11 +3,21 @@ use crate::value::Value;
 use ordered_float::OrderedFloat;
 use std::collections::{BTreeMap, HashMap};
 
+/// The ToDynamic trait allows a type to emit a representation of itself
+/// as the Value type.
+/// This trait can be derived.
 pub trait ToDynamic {
     fn to_dynamic(&self) -> Value;
 }
 
+/// The PlaceDynamic trait is used by derived implementations of FromDynamic
+/// to implement flattened conversions.
+/// Deriving FromDynamic for a struct will usually also derive
+/// PlaceDynamic for the same struct.
+/// You do not typically consume PlaceDynamic directly.
 pub trait PlaceDynamic {
+    /// Convert from Self to Value, by storing directly into the
+    /// target Object.
     fn place_dynamic(&self, place: &mut Object);
 }
 

wezterm-dynamic/src/value.rs

@@ -2,6 +2,10 @@ use crate::array::Array;
 use crate::object::Object;
 use ordered_float::OrderedFloat;
 
+/// Represents values of various possible other types.
+/// Value is intended to be convertible to the same set
+/// of types as Lua and is a superset of the types possible
+/// in TOML and JSON.
 #[derive(Clone, Debug, PartialEq, Hash, Eq, Ord, PartialOrd)]
 pub enum Value {
     Null,