Improve docs and remove unused type params

Author: ohsayan

src/actions.rs

@@ -17,7 +17,7 @@
 
 //! # Actions
 //!
-//! This module contains macros and other methods for running actions. To run actions:
+//! This module contains traits for running actions. To run actions:
 //! - For the `sync` feature, add this import:
 //!     ```
 //!     use skytable::actions::Actions;
@@ -50,7 +50,9 @@ use crate::Response;
 use core::{future::Future, pin::Pin};
 use std::io::ErrorKind;
 
+/// The error string returned when the snapshot engine is busy
 pub const ERR_SNAPSHOT_BUSY: &str = "err-snapshot-busy";
+/// The error string returned when periodic snapshots are busy
 pub const ERR_SNAPSHOT_DISABLED: &str = "err-snapshot-disabled";
 
 /// Errors while running actions
@@ -152,26 +154,26 @@ impl<T> AsyncActions for T where T: AsyncSocket {}
 implement_actions!(
     /// Get the number of keys present in the database
     fn dbsize() -> usize {
-        {Query::from("dbsize")}
+        { Query::from("dbsize") }
         Response::Item(Element::UnsignedInt(int)) => int as usize
     }
     /// Deletes a single or a number of keys
     ///
     /// This will return the number of keys that were deleted
-    fn del<T: IntoSkyhashBytes>(key: impl IntoSkyhashAction + 's) -> usize {
-        {Query::from("del").arg(key)}
+    fn del(key: impl IntoSkyhashAction + 's) -> usize {
+        { Query::from("del").arg(key) }
         Response::Item(Element::UnsignedInt(int)) => int as usize
     }
     /// Checks if a key (or keys) exist(s)
     ///
     /// This will return the number of keys that do exist
-    fn exists<T: IntoSkyhashBytes>(key: impl IntoSkyhashAction + 's) -> usize {
-        {Query::from("exists").arg(key)}
+    fn exists(key: impl IntoSkyhashAction + 's) -> usize {
+        { Query::from("exists").arg(key) }
         Response::Item(Element::UnsignedInt(int)) => int as usize
     }
     /// Removes all the keys present in the database
     fn flushdb() -> () {
-        {Query::from("flushdb")}
+        { Query::from("flushdb") }
         Response::Item(Element::RespCode(RespCode::Okay)) => {}
     }
     /// Get the value of a key
@@ -247,7 +249,7 @@ implement_actions!(
     }
     /// Deletes all the provided keys if they exist or doesn't do anything at all. This method
     /// will return true if all the provided keys were deleted, else it will return false
-    fn sdel<T: IntoSkyhashBytes>(keys: impl IntoSkyhashAction + 's) -> bool {
+    fn sdel(keys: impl IntoSkyhashAction + 's) -> bool {
         { Query::from("sdel").arg(keys) }
         Response::Item(Element::RespCode(RespCode::Okay)) => true,
         Response::Item(Element::RespCode(RespCode::NotFound)) => false

src/lib.rs

@@ -63,6 +63,12 @@
 //! ```
 //!
 //! Way to go — you're all set! Now go ahead and run more advanced queries!
+//! 
+//! ## Going advanced
+//! 
+//! Now that you know how you can run basic queries, check out the [`actions`] module documentation for learning
+//! to use actions and the [`types`] module documentation for implementing your own Skyhash serializable
+//! types.
 //!
 //! ## Async API
 //!

src/types.rs

@@ -20,6 +20,61 @@
 //! This module contains a collection of enumerations and traits that are used for converting multiple
 //! types, either primitve or user-defined, into Skyhash serializable items.
 //!
+//! 
+//! ## Implementing a Skyhash serializable type
+//! If you have an object that can be turned into a [`String`] or a sequence of [`String`] objects, then
+//! your type can be serialized by Skyhash (this might change in the future with more types being supported).
+//! Here is a simple example:
+//! ```
+//! use skytable::actions::Actions;
+//! use skytable::types::{IntoSkyhashAction, IntoSkyhashBytes, GetIterator};
+//! use skytable::Query;
+//! 
+//! /// Our custom element that adds "cool" to the end of every string when serialized
+//! struct CoolString(String);
+//! 
+//! impl IntoSkyhashBytes for CoolString {
+//!     fn into_string(&self) -> String {
+//!         let mut st = self.0.to_string();
+//!         // add cool
+//!         st.push_str("cool");
+//!         st
+//!     }
+//! }
+//! 
+//! /// Our custom sequence of `CoolString` objects
+//! struct CoolStringCollection(Vec<CoolString>);
+//! 
+//! impl IntoSkyhashAction for CoolStringCollection {
+//!     fn push_into_query(&self, query: &mut Query) {
+//!         self.0.iter().for_each(|item| query.push(item.into_string()));
+//!     }
+//!     fn incr_len_by(&self) -> usize {
+//!         self.0.len()
+//!     }
+//! }
+//! 
+//! // And finally implement `GetIterator` for use with some actions that need them
+//! 
+//! impl GetIterator<CoolString> for CoolStringCollection {
+//!     fn get_iter(&self) -> std::slice::Iter<'_, CoolString> {
+//!         self.0.iter()
+//!     }
+//! }
+//! 
+//! // You can now directly append your custom element to queries
+//! fn main() {
+//!     let mut q = Query::new();
+//!     let cool = CoolString(String::from("sayan is "));
+//!     q.push(cool);
+//!     let other_cools = CoolStringCollection(vec![
+//!             CoolString("ferris is ".to_owned()),
+//!             CoolString("llvm is ".to_owned())
+//!     ]);
+//!     q.push(other_cools);
+//!     assert_eq!(q, Query::from(vec!["sayan is cool", "ferris is cool", "llvm is cool"]));
+//! }
+//! ```
 
 use crate::Query;
 
@@ -181,7 +236,8 @@ pub enum SnapshotResult {
     Busy,
 }
 
-/// Implement this trait for methods in [`AsyncActions`] or [`Actions`] that need them
+/// Implement this trait for methods in [`crate::actions`] that need them. See the
+/// [module level documentation](crate::types) for more information
 pub trait GetIterator<T: IntoSkyhashBytes>: IntoSkyhashAction {
     fn get_iter(&self) -> std::slice::Iter<T>;
 }