diff --git a/src/durability.rs b/src/durability.rs index 146c5800..32a5ba0f 100644 --- a/src/durability.rs +++ b/src/durability.rs @@ -1,4 +1,5 @@ -/// Describes how likely a value is to change -- how "durable" it is. +/// Describes how likely a value is to change—how "durable" it is. +/// /// By default, inputs have `Durability::LOW` and interned values have /// `Durability::HIGH`. But inputs can be explicitly set with other /// durabilities. diff --git a/src/function.rs b/src/function.rs index cd433f85..24cbb130 100644 --- a/src/function.rs +++ b/src/function.rs @@ -78,6 +78,7 @@ pub trait Configuration: Any { } /// Function ingredients are the "workhorse" of salsa. +/// /// They are used for tracked functions, for the "value" fields of tracked structs, and for the fields of input structs. /// The function ingredient is fairly complex and so its code is spread across multiple modules, typically one per method. /// The main entry points are: diff --git a/src/id.rs b/src/id.rs index 5ff4e6bb..859039ac 100644 --- a/src/id.rs +++ b/src/id.rs @@ -3,6 +3,7 @@ use std::hash::Hash; use std::num::NonZeroU32; /// The `Id` of a salsa struct in the database [`Table`](`crate::table::Table`). +/// /// The higher-order bits of an `Id` identify a [`Page`](`crate::table::Page`) /// and the low-order bits identify a slot within the page. /// diff --git a/src/interned.rs b/src/interned.rs index 661c85cb..9ff667a3 100644 --- a/src/interned.rs +++ b/src/interned.rs @@ -46,7 +46,8 @@ pub struct JarImpl { phantom: PhantomData, } -/// The interned ingredient has the job of hashing values of type `Data` to produce an `Id`. +/// The interned ingredient hashes values of type `Data` to produce an `Id`. +/// /// It used to store interned structs but also to store the id fields of a tracked struct. /// Interned values endure until they are explicitly removed in some way. pub struct IngredientImpl { diff --git a/src/revision.rs b/src/revision.rs index a98a4585..a7445610 100644 --- a/src/revision.rs +++ b/src/revision.rs @@ -5,8 +5,9 @@ use std::sync::atomic::{AtomicUsize, Ordering}; /// because we want to use a `NonZeroUsize`. const START: usize = 1; -/// A unique identifier for the current version of the database; each -/// time an input is changed, the revision number is incremented. +/// A unique identifier for the current version of the database. +/// +/// Each time an input is changed, the revision number is incremented. /// `Revision` is used internally to track which values may need to be /// recomputed, but is not something you should have to interact with /// directly as a user of salsa. diff --git a/src/tracked_struct.rs b/src/tracked_struct.rs index 04351c8d..6b83d0ae 100644 --- a/src/tracked_struct.rs +++ b/src/tracked_struct.rs @@ -120,13 +120,14 @@ pub trait TrackedStructInDb: SalsaStructInDb { } /// Created for each tracked struct. -/// This ingredient only stores the "id" fields. -/// It is a kind of "dressed up" interner; -/// the active query + values of id fields are hashed to create the tracked struct id. -/// The value fields are stored in [`crate::function::FunctionIngredient`] instances keyed by the tracked struct id. -/// Unlike normal interners, tracked struct indices can be deleted and reused aggressively: -/// when a tracked function re-executes, -/// any tracked structs that it created before but did not create this time can be deleted. +/// +/// This ingredient only stores the "id" fields. It is a kind of "dressed up" interner; +/// the active query + values of id fields are hashed to create the tracked +/// struct id. The value fields are stored in [`crate::function::FunctionIngredient`] +/// instances keyed by the tracked struct id. Unlike normal interners, tracked +/// struct indices can be deleted and reused aggressively: when a tracked +/// function re-executes, any tracked structs that it created before but did +/// not create this time can be deleted. pub struct IngredientImpl where C: Configuration, diff --git a/src/tracked_struct/tracked_field.rs b/src/tracked_struct/tracked_field.rs index bfdc6c2a..d5c214ad 100644 --- a/src/tracked_struct/tracked_field.rs +++ b/src/tracked_struct/tracked_field.rs @@ -5,6 +5,7 @@ use crate::{ingredient::Ingredient, zalsa::IngredientIndex, Database, Id}; use super::{Configuration, Value}; /// Created for each tracked struct. +/// /// This ingredient only stores the "id" fields. /// It is a kind of "dressed up" interner; /// the active query + values of id fields are hashed to create the tracked struct id. diff --git a/src/zalsa.rs b/src/zalsa.rs index ab52814d..2f8fa95f 100644 --- a/src/zalsa.rs +++ b/src/zalsa.rs @@ -16,14 +16,17 @@ use crate::views::Views; use crate::zalsa_local::ZalsaLocal; use crate::{Database, DatabaseKeyIndex, Durability, Id, Revision}; -/// Internal plumbing trait; implemented automatically when `#[salsa::db]`(`crate::db`) is attached to your database struct. -/// Contains methods that give access to the internal data from the `storage` field. +/// Internal plumbing trait. +/// +/// [`ZalsaDatabase`] is created automatically when [`#[salsa::db]`](`crate::db`) +/// is attached to a database struct. it Contains methods that give access +/// to the internal data from the `storage` field. /// /// # Safety /// /// The system assumes this is implemented by a salsa procedural macro /// which makes use of private data from the [`Storage`](`crate::storage::Storage`) struct. -/// Do not implement this yourself, instead, apply the [`salsa::db`](`crate::db`) macro +/// Do not implement this yourself, instead, apply the [`#[salsa::db]`](`crate::db`) macro /// to your database. pub unsafe trait ZalsaDatabase: Any { /// Plumbing method: access both zalsa and zalsa-local at once. @@ -61,6 +64,7 @@ pub struct StorageNonce; static NONCE: NonceGenerator = NonceGenerator::new(); /// An ingredient index identifies a particular [`Ingredient`] in the database. +/// /// The database contains a number of jars, and each jar contains a number of ingredients. /// Each ingredient is given a unique index as the database is being created. #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]