adding comments (#2147)

lib/src/ctx/mod.rs

@@ -1,3 +1,16 @@
+//! This module defines and handles the `context` for the SurrealDB database.
+//! ## Concept
+//! The context is shared through the code. To understand the context of `context` we must appreciate that
+//! there are different layers to the SurrealDB database. Whilst at this point in time there is no definition
+//! of all the layers in code, we can illustrate the layers with the following lifecycle of a database request:
+//! - we start with an SQL statement
+//! - the SQL statement is then parsed into an operation
+//! - we then go down to the key value store . . .
+//! Here we can see that the database request is handled by different layers. The `context` is the shared state.
+//! Each layer can clone the `context` but it must be noted that the values of the `context` are not cloned. A
+//! simple example of using the `context` is to keep track of the duration of the request, or if the process has
+//! been cancelled or not.
+
 // Copyright 2017 Thomas de Zeeuw
 //
 // https://docs.rs/io-context/0.2.0/io_context/

lib/src/dbs/mod.rs

@@ -1,3 +1,7 @@
+//! Datastore module which is the core of the database node.
+//! In this module we essentially manage the entire lifecycle of a database request acting as the
+//! glue between the API and the response. In this module we use channels as a transport layer
+//! and executors to process the operations. This module also gives a `context` to the transaction.
 mod auth;
 mod executor;
 mod iterate;

lib/src/doc/mod.rs

@@ -1,3 +1,9 @@
+//! This module defines the lifecycle of everything that happens in a document.
+//! A document is a row that has the following:
+//! - `Thing`: name of the table and ID of the record
+//! - `current`: value after the transaction
+//! - `initial`: value before the transaction
+//! - `id`: traditionally an integer but can be an object or collection such as an array
 pub(crate) use self::document::*;
 
 #[cfg(not(target_arch = "wasm32"))]

lib/src/fnc/mod.rs

@@ -1,3 +1,4 @@
+//! Executes functions from SQL. If there is an SQL function it will be defined in this module.
 use crate::ctx::Context;
 use crate::err::Error;
 use crate::sql::value::Value;

lib/src/key/mod.rs

@@ -1,3 +1,4 @@
+//! How the keys are structured in the key value store
 ///
 /// KV              /
 /// NS              /!ns{ns}

lib/src/kvs/mod.rs

@@ -1,3 +1,17 @@
+//! The module defining the key value store.
+//! Everything related the transaction for the key value store is defined in the `tx.rs` file.
+//! This module enables the following operations on the key value store:
+//! - get
+//! - set
+//! - delete
+//! - put
+//! These operations can be processed by the following storage engines:
+//! - `fdb`: [FoundationDB](https://github.com/apple/foundationdb/) a distributed database designed to handle large volumes of structured data across clusters of commodity servers
+//! - `indxdb`: WASM based database to store data in the browser
+//! - `rocksdb`: [RocksDB](https://github.com/facebook/rocksdb) an embeddable persistent key-value store for fast storage
+//! - `speedb`: [SpeedyDB](https://github.com/speedb-io/speedb) fork of rocksDB making it faster (Redis is using speedb but this is not acid transactions)
+//! - `tikv`: [TiKV](https://github.com/tikv/tikv) a distributed, and transactional key-value database
+//! - `mem`: in-memory database
 mod cache;
 mod ds;
 mod fdb;