docs: enhancement

README.md

@@ -45,67 +45,19 @@ NOTE: `native_db` requires `native_model` to work.
 
 Active development. The API is not stable yet and may change in the future.
 
-# Usage
-
-- With Tauri: [native_db_tauri_vanilla](https://github.com/vincent-herlemont/native_db_tauri_vanilla)
-
-# Usual API
-
-### ⚠️ The current release is `0.6.1`, follow this [link](https://github.com/vincent-herlemont/native_db/tree/0.6.1?tab=readme-ov-file#usual-api) to see the documentation.
-
-- [**Models**](https://docs.rs/native_db/latest/native_db/struct.Models.html)
-    - [**new**](https://docs.rs/native_db/latest/native_db/struct.Models.html#method.new) a new model.
-    - [**define**](https://docs.rs/native_db/latest/native_db/struct.Models.html#method.define) a model.
-- [**Builder**](https://docs.rs/native_db/latest/native_db/struct.Builder.html)  
-    - [**create**](https://docs.rs/native_db/latest/native_db/struct.Builder.html#method.create) / [**open**](https://docs.rs/native_db/latest/native_db/struct.Builder.html#method.open) a database.
-    - [**create_in_memory**](https://docs.rs/native_db/latest/native_db/struct.Builder.html#method.create_in_memory) an in-memory database.
-- [**Database**](https://docs.rs/native_db/latest/native_db/struct.Database.html)
-    - [**snapshot**](https://docs.rs/native_db/latest/native_db/struct.Database.html#method.snapshot) the database.
-    - **rw_transaction** open a read-write transaction.
-        - [**insert**](https://docs.rs/native_db/latest/native_db/transaction/struct.RwTransaction.html#method.insert) a new item.
-        - [**update**](https://docs.rs/native_db/latest/native_db/transaction/struct.RwTransaction.html#method.update) an existing item.
-        - [**remove**](https://docs.rs/native_db/latest/native_db/transaction/struct.RwTransaction.html#method.remove) an existing item.
-        - [**commit**](https://docs.rs/native_db/latest/native_db/transaction/struct.RwTransaction.html#method.commit) the transaction.
-        - [**abort**](https://docs.rs/native_db/latest/native_db/transaction/struct.RwTransaction.html#method.abort) the transaction.
-        - [**migrate**](https://docs.rs/native_db/latest/native_db/transaction/struct.RwTransaction.html#method.migrate) a model.
-        - plus all read-only transaction APIs.
-    - **r_transaction** open a read-only transaction.
-        - **get**
-            - [**primary**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.RGet.html#method.primary) an item by its primary key.
-            - [**secondary**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.RGet.html#method.secondary) an item by its secondary key.
-        - **scan**
-            - **primary**
-                - [**all**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.PrimaryScan.html#method.all) items.
-                - [**start_with**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.PrimaryScan.html#method.start_with) items with a primary key starting with a given value.
-                - [**range**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.PrimaryScan.html#method.range) items with a primary key in a given range.
-            - **secondary**
-                - [**all**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.SecondaryScan.html#method.all) items with a given secondary key.
-                - [**start_with**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.SecondaryScan.html#method.start_with) items with a secondary key starting with a given value.
-                - [**range**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.SecondaryScan.html#method.range) items with a secondary key in a given range.
-        - **len**
-            - [**primary**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.RLen.html#method.primary) the number of items.
-            - [**secondary**](https://docs.rs/native_db/latest/native_db/transaction/query/struct.RLen.html#method.secondary) the number of items with a given secondary key.
-    - **watch** real-time subscriptions via [std channel](https://doc.rust-lang.org/std/sync/mpsc/fn.channel.html) based or [tokio channel](https://docs.rs/tokio/latest/tokio/sync/mpsc/fn.unbounded_channel.html) based depending on the feature `tokio`.
-        - **get**
-            - [**primary**](https://docs.rs/native_db/latest/native_db/watch/query/struct.WatchGet.html#method.primary) an item by its primary key.
-            - [**secondary**](https://docs.rs/native_db/latest/native_db/watch/query/struct.WatchGet.html#method.secondary) an item by its secondary key.
-        - **scan**
-            - **primary**
-                - [**all**](https://docs.rs/native_db/latest/native_db/watch/query/struct.WatchScanPrimary.html#method.all) items.
-                - [**start_with**](https://docs.rs/native_db/latest/native_db/watch/query/struct.WatchScanPrimary.html#method.start_with) items with a primary key starting with a given value.
-                - [**range**](https://docs.rs/native_db/latest/native_db/watch/query/struct.WatchScanPrimary.html#method.range) items with a primary key in a given range.
-            - **secondary**
-                - [**all**](https://docs.rs/native_db/latest/native_db/watch/query/struct.WatchScanSecondary.html#method.all) items with a given secondary key.
-                - [**start_with**](https://docs.rs/native_db/latest/native_db/watch/query/struct.WatchScanSecondary.html#method.start_with) items with a secondary key starting with a given value.
-                - [**range**](https://docs.rs/native_db/latest/native_db/watch/query/struct.WatchScanSecondary.html#method.range) items with a secondary key in a given range.
+# How to use?
 
+- [Documentation API](https://docs.rs/native_db/latest/native_db/#api)
+- [Quick Start](https://docs.rs/native_db/latest/native_db/#quick_start)
+- Full example with Tauri: [native_db_tauri_vanilla](https://github.com/vincent-herlemont/native_db_tauri_vanilla)
 
 # Example
 
 ```rust
 use serde::{Deserialize, Serialize};
 use native_db::*;
 use native_model::{native_model, Model};
+use once_cell::sync::Lazy;
 
 #[derive(Serialize, Deserialize, PartialEq, Debug)]
 #[native_model(id = 1, version = 1)]
@@ -117,13 +69,18 @@ struct Item {
     name: String,
 }
 
-fn main() -> Result<(), db_type::Error> {
+// Define the models
+// The lifetime of the models needs to be longer or equal to the lifetime of the database.
+// In many cases, it is simpler to use a static variable but it is not mandatory.
+static MODELS: Lazy<Models> = Lazy::new(|| {
     let mut models = Models::new();
-    // Initialize the model
-    models.define::<Item>()?;
-
+    models.define::<Item>().unwrap();
+    models
+});
+
+fn main() -> Result<(), db_type::Error> {
     // Create a database in memory
-    let mut db = Builder::new().create_in_memory(&models)?;
+    let mut db = Builder::new().create_in_memory(&MODELS)?;
 
     // Insert data (open a read-write transaction)
     let rw = db.rw_transaction().unwrap();

src/database.rs

@@ -41,6 +41,19 @@ pub struct Database<'a> {
 
 impl Database<'_> {
     /// Creates a new read-write transaction.
+    /// This transaction allows you to read and write data.
+    /// 
+    /// - Write operations:
+    ///     - [`insert`](crate::transaction::RwTransaction::insert) - Insert a item.
+    ///     - [`update`](crate::transaction::RwTransaction::update) - Update a item.
+    ///     - [`remove`](crate::transaction::RwTransaction::remove) - Remove a item.
+    ///     - [`migrate`](crate::transaction::RwTransaction::migrate) - Migrate a model, affect all items.
+    ///     - [`commit`](crate::transaction::RwTransaction::commit) - Commit the transaction.
+    ///     - [`abort`](crate::transaction::RwTransaction::abort) - Abort the transaction.
+    /// - Read operations:
+    ///    - [`get`](crate::transaction::RwTransaction::get) - Get a item.
+    ///    - [`scan`](crate::transaction::RwTransaction::scan) - Scan items.
+    ///    - [`len`](crate::transaction::RwTransaction::len) - Get the number of items.
     pub fn rw_transaction(&self) -> Result<RwTransaction> {
         let rw = self.instance.redb_database()?.begin_write()?;
         let write_txn = RwTransaction {
@@ -55,6 +68,12 @@ impl Database<'_> {
     }
 
     /// Creates a new read-only transaction.
+    /// This transaction allows you to read data.
+    /// 
+    /// - Read operations:
+    ///   - [`get`](crate::transaction::RTransaction::get) - Get a item.
+    ///   - [`scan`](crate::transaction::RTransaction::scan) - Scan items.
+    ///   - [`len`](crate::transaction::RTransaction::len) - Get the number of items.
     pub fn r_transaction(&self) -> Result<RTransaction> {
         let txn = self.instance.redb_database()?.begin_read()?;
         let read_txn = RTransaction {
@@ -69,6 +88,9 @@ impl Database<'_> {
 
 impl Database<'_> {
     /// Watch queries.
+    /// 
+    /// - [`get`](crate::watch::query::Watch::get) - Watch a item.
+    /// - [`scan`](crate::watch::query::Watch::scan) - Watch items.
     pub fn watch(&self) -> Watch {
         Watch {
             internal: InternalWatch {

src/database_builder.rs

@@ -61,13 +61,12 @@ impl Builder {
 }
 
 impl Builder {
-    /// Similar to [redb::Builder::new()](https://docs.rs/redb/latest/redb/struct.Builder.html#method.new).
+    /// Construct a new [Builder] with sensible defaults.
     pub fn new() -> Self {
         Self {
             database_configuration: Configuration {
                 cache_size_bytes: None,
             },
-            // models_builder: HashMap::new(),
         }
     }
 
@@ -77,9 +76,9 @@ impl Builder {
         self
     }
 
-    // /// Creates a new `Db` instance using the given path.
-    // ///
-    // /// Similar to [redb::Builder.create(...)](https://docs.rs/redb/latest/redb/struct.Builder.html#method.create)
+    /// Creates a new `Db` instance using the given path.
+    ///
+    /// Similar to [redb::Builder.create(...)](https://docs.rs/redb/latest/redb/struct.Builder.html#method.create)
     pub fn create<'a>(&self, models: &'a Models, path: impl AsRef<Path>) -> Result<Database<'a>> {
         let builder = self.database_configuration.new_rdb_builder();
         let database_instance = DatabaseInstance::create_on_disk(builder, path)?;