Expand docs.

microrm/src/lib.rs

@@ -20,9 +20,68 @@
 //! microrm pushes the Rust type system somewhat to provide better ergonomics, so the MSRV is
 //! currently 1.75. Don't be scared off by the web of traits in the `schema` module --- you should
 //! never need to interact with any of them!
+//!
+//! ### Examples
+//!
+//! For the simplest kind of database schema, a key-value store, one possible microrm
+//! implementation of it might look like the following:
+//!
+//! ```
+//! use microrm::prelude::*;
+//!
+//! #[derive(Entity)]
+//! struct KVEntry {
+//!     #[key]
+//!     key: String,
+//!     value: String,
+//! }
+//!
+//! #[derive(Database)]
+//! struct KVDB {
+//!     kvs: microrm::IDMap<KVEntry>,
+//! }
+//!
+//! # fn main() -> Result<(), microrm::Error> {
+//! let db = KVDB::open_path(":memory:")?;
+//! db.kvs.insert(KVEntry {
+//!     key: "example_key".to_string(),
+//!     value: "example_value".to_string()
+//! })?;
+//!
+//! // can get with a String reference
+//! assert_eq!(
+//!     db.kvs.keyed(&String::from("example_key")).get()?.map(|v| v.value.clone()),
+//!     Some("example_value".to_string()));
+//! // thanks to the QueryEquivalent trait, we can also just use a plain &str
+//! assert_eq!(
+//!     db.kvs.keyed("example_key").get()?.map(|v| v.value.clone()),
+//!     Some("example_value".to_string()));
+//!
+//! // obviously, if we get another KV entry with a missing key, it doesn't come back...
+//! assert_eq!(db.kvs.keyed("another_example_key").get()?.is_some(), false);
+//!
+//! // note that the above all return an Option<Stored<T>>. when using filters on arbitrary
+//! // columns, a Vec<Stored<T>> is returned:
+//! assert_eq!(
+//!     db
+//!         .kvs
+//!         // note that the column constant uses CamelCase
+//!         .with(KVEntry::Value, "example_value")
+//!         .get()?
+//!         .into_iter()
+//!         .map(|v| v.wrapped().value).collect::<Vec<_>>(),
+//!     vec!["example_value".to_string()]);
+//!
+//! # Ok(())
+//! # }
+//!
+//! ```
 
 #![warn(missing_docs)]
 
+// this requires clippy 1.78
+// #![warn(clippy::empty_docs)]
+
 // to make the proc_macros work inside the microrm crate; needed for tests and the metaschema.
 extern crate self as microrm;
 
@@ -31,6 +90,8 @@ pub mod db;
 mod query;
 pub mod schema;
 
+pub use schema::{AssocDomain, AssocMap, AssocRange, IDMap, Relation, Serialized, Stored};
+
 #[cfg(feature = "clap")]
 pub mod cli;
 

microrm/src/schema.rs

@@ -16,7 +16,10 @@ use crate::{
 };
 use crate::{DBResult, Error};
 
-use self::{datum::{ConcreteDatum, DatumDiscriminatorRef}, entity::EntityPartList};
+use self::{
+    datum::{ConcreteDatum, DatumDiscriminatorRef},
+    entity::EntityPartList,
+};
 
 /// Types related to datums, or struct fields.
 pub mod datum;
@@ -114,9 +117,9 @@ impl<T: Entity> PartialEq for Stored<T> {
 
 /// Represents an arbitrary relation between two types of entities.
 ///
-/// In its most generic form, stores an arbitrary set of `(Domain::ID, Range::ID)` pairs used to
-/// define the relation. Can be restricted to be injective if this is desired. Doing so will incur
-/// a small runtime cost, since an extra index must be maintained.
+/// In its most generic form, this represents a table that stores an arbitrary set of `(Domain::ID,
+/// Range::ID)` pairs used to define the relation. Can be restricted to be injective if this is
+/// desired. Doing so will incur a small runtime cost, since an extra index must be maintained.
 pub trait Relation: 'static {
     /// The domain of the relation, aka the "pointed-from" type. This is interchangeable with
     /// `Range` unless `INJECTIVE` is set to true.