docs: Updated documentation

README.md

@@ -6,18 +6,26 @@ SPDX-License-Identifier: MIT OR Apache-2.0
 
 # naphtha
 
+*Universal database connection layer*
+
 [![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-informational?style=flat-square)](COPYRIGHT.md)
 
 [![Crates.io](https://img.shields.io/crates/v/naphtha.svg)](https://crates.io/crates/naphtha) [![docs.rs](https://img.shields.io/docsrs/naphtha?style=flat-square)](https://docs.rs/naphtha) **naphtha**
 
 [![Crates.io](https://img.shields.io/crates/v/naphtha-proc-macro.svg)](https://crates.io/crates/naphtha-proc-macro) **naphtha-proc-macro**
 
-Please checkout the [documentation page](https://docs.rs/naphtha) for information and examples (also see examples folder in [naphtha](./naphtha/examples))
+Please checkout the [documentation page](https://docs.rs/naphtha) for more information (also see examples folder in [naphtha](./naphtha/examples))
 
 If you have questions, want to contribute or have any other type of request, your invited to create an issue or visit the [openprobst.dev](https://openprobst.dev) discord server.
 
 [![](https://img.shields.io/discord/855726181142495242?color=154683&label=discord&style=flat-square)](https://discord.gg/nx7YtsjEbT)
 
+## About
+
+This crate is to simplify the creation and usage of models that require a database connection. If applied correct, changing the database type is only a feature flag away.
+
+The models can also be compiled and used without database connection support for better usage on server and client side.
+
 ## Roadmap
 
 - [x] Connect to database using a wrapper, defining the base for interchangeable Databases
@@ -27,9 +35,13 @@ If you have questions, want to contribute or have any other type of request, you
 - [x] Thread safe sharing of the database connection
 - [x] Integrate `barrel` crate for writing migrations in Rust, available at runtime
 - [x] Implement support for `diesel::MySqlConnection`
-- [ ] Implement support for `diesel::PgConnection`
-- [ ] Connection pooling
-- [ ] More databases!!!
+- [x] Implement support for `diesel::PgConnection`
+- [ ] Connection pooling?
+- [ ] More databases?
+
+## Troubleshooting
+
+It is very easy to get a whole bunch of `trait bound not satisfied` error messages when your model is not configured correctly. Make sure that your `schema` module and the containing `table!` definition is in line with your `model` definition and that it uses the correct types defined by [barrel](https://docs.rs/barrel).
 
 ## Contributing
 

naphtha/src/lib.rs

@@ -15,11 +15,12 @@
 //!
 //! * Most common function implementations `insert`, `update`, `remove` for your
 //! models.
+//! * Custom transactions provided by the `custom` function
 //! * [DatabaseUpdateHandler](DatabaseUpdateHandler) enables you to change the models values before and
 //! after the `update` transaction to the database.
 //! * Change database on specific model in your application without the need to
 //! change your code.
-//! * Possibility to query a model from the database by using one of its member *(NOT FINISHED YET)*.
+//! * Possibility to query a model from the database by using one of its member.
 //! * Integrated [barrel] for writing your SQL migrations.
 //! * Thread safe handling of the database connection.
 //!
@@ -45,42 +46,24 @@
 //!
 //! ### Defining a model and use database connection
 //!
-//! ```rust
-//! #[macro_use]
-//! extern crate diesel;
-//! #[macro_use]
-//! extern crate naphtha;
-//!
-//! use {
-//!     naphtha::{
-//!         model,
-//!         DatabaseModel,
-//!         DatabaseModelModifier,
-//!         DatabaseInsertHandler,
-//!         DatabaseUpdateHandler,
-//!         DatabaseRemoveHandler
-//!     },
-//!     diesel::table
-//! };
-//! #[cfg(any(feature = "barrel-sqlite", feature = "barrel-mysql", feature = "barrel-pg"))]
-//! use naphtha::barrel::{types, DatabaseSqlMigration, Migration};
-//!
-//! // It is recommended to wrap the actual used database type in a crate-global
-//! // alias. If the database is changed later, this is the only line that needs
-//! // to be adjusted to the new database type.
-//! pub(crate) type DbBackend = diesel::SqliteConnection;
+//! To create a model and its database integration, the following code is required.
+//! *Note that this is an excerpt, see the `examples` folder in the repository for
+//! a full working example.*
 //!
+//! ```ignore
 //! #[model(table_name = "persons")]
 //! pub struct Person {
 //!     id: i32,
 //!     pub description: Option<String>,
+        pub updated_at: NaiveDateTime,
 //! }
 //!
 //! pub mod schema {
 //!     table! {
 //!         persons (id) {
 //!             id -> Int4,
 //!             description -> Nullable<Varchar>,
+                updated_at -> Timestamp,
 //!         }
 //!     }
 //! }
@@ -104,16 +87,12 @@
 //!     }
 //! }
 //!
-//! // do not implement custom changes before and after the transactions
-//! // to the database.
+//! // Define your custom changes to the model before and after the transactions.
 //! impl<T> naphtha::DatabaseUpdateHandler<T> for Person {}
 //! impl<T> naphtha::DatabaseRemoveHandler<T> for Person {}
 //! impl<T> naphtha::DatabaseInsertHandler<T> for Person {}
 //!
-//! #[cfg(any(
-//!     feature = "barrel-full",
-//!     feature = "barrel-sqlite",
-//! ))]
+//! // This implements your database migration functions.
 //! impl DatabaseSqlMigration for Person {
 //!     fn migration_up(migration: &mut Migration) {
 //!         use naphtha::DatabaseModel;
@@ -133,6 +112,8 @@
 //! fn main() {
 //!     use naphtha::{DatabaseConnection, DatabaseConnect};
 //!     let db = DatabaseConnection::connect(":memory:").unwrap();
+//!     // p is to be mutable because the insert function updates the id member
+//!     // to the one given by the database.
 //!     let mut p = Person {
 //!         id: Person::default_primary_key(),
 //!         description: Some("The new person is registered".into()),
@@ -147,7 +128,7 @@
 //!     });
 //!
 //!     p.remove(&db);
-//!     // p not available anymore
+//!     // p not available anymore in the database
 //! }
 //! ```