Update docs

Author: Bennett Hardwick

src/lib.rs

@@ -7,7 +7,11 @@
 //! ## Usage
 //!
 //! To use Cryptonamo, you must first create a table in DynamoDB.
-//! The table must have a primary key and sort key, both of type String.
+//! The table must have a at least partition key, sort key, and term field - all of type String.
+//!
+//! Cryptonamo also expects a Global Secondary Index called "TermIndex" to exist if you want to
+//! search and query against records. This index should project all fields and have a key schema
+//! that is a hash on the term attribute.
 //!
 //! You can use the the `aws` CLI to create a table with an appropriate schema as follows:
 //!
@@ -22,14 +26,15 @@
 //!         AttributeName=pk,KeyType=HASH \
 //!         AttributeName=sk,KeyType=RANGE \
 //!     --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5 \
-//!     --global-secondary-indexes "IndexName=TermIndex,KeySchema=[{AttributeName=term,KeyType=HASH},{AttributeName=pk,KeyType=RANGE}],Projection={ProjectionType=ALL},ProvisionedThroughput={ReadCapacityUnits=5,WriteCapacityUnits=5}"
+//!     --global-secondary-indexes "IndexName=TermIndex,KeySchema=[{AttributeName=term,KeyType=HASH}],Projection={ProjectionType=ALL},ProvisionedThroughput={ReadCapacityUnits=5,WriteCapacityUnits=5}"
 //! ```
 //!
 //! See below for more information on schema design for Cryptonamo tables.
 //!
 //! ### Annotating a Cryptanomo Type
 //!
-//! To use Cryptonamo, you must first annotate a struct with the `Cryptonamo` derive macro.
+//! To use Cryptonamo, you must first annotate a struct with the `Encryptable` derive macro, as
+//! well as the `Searchable` and `Decryptable` macros if you want to support those features.
 //!
 //! ```rust
 //! use cryptonamo::{Searchable, Decryptable, Encryptable};
@@ -42,7 +47,7 @@
 //! }
 //! ```
 //!
-//! The `Cryptonamo` derive macro will generate implementations of the following traits:
+//! These derive macros will generate implementations for the following traits of the same name:
 //!
 //! * `Decryptable` - a trait that allows you to decrypt a record from DynamoDB
 //! * `Encryptable` - a trait that allows you to encrypt a record for storage in DynamoDB
@@ -52,8 +57,9 @@
 //!
 //! ### Controlling Encryption
 //!
-//! By default, all fields on a `Cryptanomo` type are encrypted and stored in the index.
-//! To store a field as a plaintext, use the `plaintext` attribute:
+//! By default, all fields on an annotated struct are stored encrypted in the table.
+//!
+//! To store a field as a plaintext, you can use the `plaintext` attribute:
 //!
 //! ```rust
 //! use cryptonamo::{Searchable, Decryptable, Encryptable};
@@ -69,16 +75,6 @@
 //! }
 //! ```
 //!
-//! Most basic rust types will work automatically but you can implement a conversion trait for [Plaintext] to support custom types.
-//!
-//! ```ignore
-//! impl From<MyType> for Plaintext {
-//!     fn from(t: MyType) -> Self {
-//!         t.as_bytes().into()
-//!     }
-//! }
-//! ```
-//!
 //! If you don't want a field stored in the the database at all, you can annotate the field with `#[cryptonamo(skip)]`.
 //!
 //!```rust
@@ -95,9 +91,11 @@
 //! }
 //! ```
 //!
+//! If you implement the `Decryptable` trait these skipped fields need to implement `Default`.
+//!
 //! ### Sort keys
 //!
-//! Cryptanomo requires every record to have a sort key and it derives it automatically based on the name of the struct.
+//! Cryptanomo requires every record to have a sort key. By default this will be derived based on the name of the struct.
 //! However, if you want to specify your own, you can use the `sort_key_prefix` attribute:
 //!
 //!```rust
@@ -115,10 +113,30 @@
 //! }
 //! ```
 //!
+//! #### Dynamic Sort keys
+//!
+//! Cryptonamo also supports specifying the sort key dynamically based on a field on the struct.
+//! You can choose the field using the `#[sort_key]` attribute.
+//!
+//! ```rust
+//! #[derive(Debug, Encryptable)]
+//! struct User {
+//!     #[partition_key]
+//!     email: String,
+//!     #[sort_key]
+//!     name: String,
+//!
+//!     #[cryptonamo(skip)]
+//!     not_required: String,
+//! }
+//! ```
+//!
+//! Sort keys will contain that value and will be prefixed by the sort key prefix.
+//!
 //! ## Indexing
 //!
 //! Cryptanomo supports indexing of encrypted fields for searching.
-//! Exact, prefix and compound match types are all supported.
+//! Exact, prefix and compound match types are currently supported.
 //! To index a field, use the `query` attribute:
 //!
 //! ```rust
@@ -136,7 +154,11 @@
 //! ```
 //!
 //! You can also specify a compound index by using the `compound` attribute.
-//! All indexes with the same compound name are combined into a single index.
+//! Indexes with the same name will be combined into the one index.
+//!
+//! Compound index names must be a combination of field names separated by a #.
+//! Fields mentioned in the compound index name that aren't correctly annottated will result in a
+//! compilation error.
 //!
 //! ```rust
 //! use cryptonamo::Encryptable;
@@ -152,8 +174,28 @@
 //! }
 //! ```
 //!
-//! **NOTE:** Compound indexes defined using the `compound` attribute are not currently working.
-//! Check out [SearchableRecord] for more information on how to implement compound indexes.
+//! It's also possible to add more than one query attribute to support querying records in multiple
+//! different ways.
+//!
+//!
+//! ```rust
+//! use cryptonamo::Encryptable;
+//!
+//! #[derive(Debug, Encryptable)]
+//! struct User {
+//!     #[cryptonamo(query = "exact")]
+//!     #[cryptonamo(query = "exact", compound = "email#name")]
+//!     #[partition_key]
+//!     email: String,
+//!     
+//!    #[cryptonamo(query = "prefix")]
+//!    #[cryptonamo(query = "exact")]
+//!    #[cryptonamo(query = "prefix", compound = "email#name")]
+//!     name: String,
+//! }
+//! ```
+//! It's important to note that the more annotations that are added to a field the more index terms that will be generated. Adding too many attributes could result in a
+//! proliferation of terms and data.
 //!
 //! ## Storing and Retrieving Records
 //!
@@ -327,6 +369,9 @@
 //! # }
 //! ```
 //!
+//! Note: if you don't have the correct indexes defined this query builder will return a runtime
+//! error.
+//!
 //! ## Table Verticalization
 //!
 //! Cryptonamo uses a technique called "verticalization" which is a popular approach to storing data in DynamoDB.
@@ -444,8 +489,6 @@
 //!
 //! ## Issues and TODO
 //!
-//! - [ ] Support for plaintext types is currently not implemented
-//! - [ ] Using the derive macros for compound macros is not working correctly (you can implement the traits directly)
 //! - [ ] Sort keys are not currently hashed (and should be)
 //!
 pub mod crypto;