update main docs

cozo-core/Cargo.toml

@@ -48,6 +48,36 @@ storage-sled = ["dep:sled"]
 ## Enables the [TiKV](https://tikv.org/) client backend
 storage-tikv = ["dep:tikv-client", "dep:tokio"]
 
+#! # Recommendation for features to enable
+#!
+#! Generally you will want the `storage-sqlite` and `graph-algo` features enabled,
+#! unless your environment makes compiling them difficult. The backup/restore functionalities
+#! are only available if `storage-sqlite` is on. Without `graph-algo` you cannot use any graph algorithms
+#! (utilities are still available),
+#! which could be OK if you only want to deal with pure Datalog.
+#!
+#! If having multiple threads
+#! running in the background is undesirable, you can enable the `nothread` feature.
+#!
+#! The `rayon` feature enables some algorithms to make use of parallelism. This is desirable in most circumstances.
+#! Naturally, it is incompatible with `nothread`.
+#!
+#! The `requests` feature allows the database to make outgoing HTTP requests to fetch data
+#! into queries -- only enable it if you need it.
+#!
+#! The `wasm` feature simply patches some functions so that they can compile on WASM platform,
+#! which lacks some std implementations at the moment. (On WASM you must also enable `nothread`).
+#! This feature will not work on any other platform.
+#!
+#! The `jemalloc` feature only makes sense for desktop and servers. It could improve performance,
+#! sometimes substantially, but you need to benchmark for your use case. It also tends to break
+#! builds on untested platforms. None of our prebuilt binaries have it enabled.
+#!
+#! Enable `storage-rocksdb` if you expect high concurrency or want better performance than SQLite,
+#! but note that RocksDB is much more resource-hungry and takes long to compile.
+#!
+#! The other storage options are just for experimentation. We do not recommend using them.
+
 [dependencies]
 casey = "0.3.3"
 either = "1.7.0"

cozo-core/src/lib.rs

@@ -24,9 +24,9 @@
 //! let result = db.run_script(script, &Default::default()).unwrap();
 //! println!("{:?}", result);
 //! ```
-//! We created an in-memory database with [`new_cozo_mem`](crate::new_cozo_mem) above.
-//! Persistent options include [`new_cozo_rocksdb`](crate::new_cozo_rocksdb),
-//! [`new_cozo_sqlite`](crate::new_cozo_sqlite) and others.
+//! We created an in-memory database above. There are other persistent options:
+//! see [DbInstance::new]. It is perfectly fine to run multiple storage engines in the same process.
+//!
 #![doc = document_features::document_features!()]
 #![warn(rust_2018_idioms, future_incompatible)]
 #![warn(missing_docs)]
@@ -68,8 +68,15 @@ pub(crate) mod storage;
 pub(crate) mod utils;
 
 #[derive(Clone)]
-/// A dispatcher for concrete storage implementations, wrapping [crate::Db].
-/// Many methods are dispatching methods -- see the corresponding methods on [crate::Db] for more details.
+/// A dispatcher for concrete storage implementations, wrapping [Db]. This is done so that
+/// client code does not have to deal with generic code constantly. You may prefer to use
+/// [Db] directly, especially if you provide a custom storage engine.
+///
+/// Many methods are dispatching methods for the corresponding methods on [Db].
+///
+/// Other methods are wrappers simplifying signatures to deal with only strings.
+/// These methods made code for interop with other languages much easier,
+/// but are not desirable if you are using Rust.
 pub enum DbInstance {
     /// In memory storage (not persistent)
     Mem(Db<MemStorage>),
@@ -89,7 +96,14 @@ pub enum DbInstance {
 
 impl DbInstance {
     /// Create a DbInstance, which is a dispatcher for various concrete implementations.
-    /// The valid kinds are `mem`, `sqlite`, `rocksdb`, `sled` and `tikv`,
+    /// The valid kinds are:
+    ///
+    /// * `mem`
+    /// * `sqlite`
+    /// * `rocksdb`
+    /// * `sled`
+    /// * `tikv`
+    ///
     /// assuming all features are enabled during compilation. Otherwise only
     /// some of the kinds are available. The `mem` kind is always available.
     ///