Fix clippy lints and improve docs

src/backend/mmap.rs

@@ -1,5 +1,3 @@
-use memmap;
-use failure;
 use failure::ResultExt;
 
 use super::Backend;
@@ -12,9 +10,9 @@ use std::io;
 #[derive(Debug)]
 struct Mmap {
     inner: memmap::MmapMut,
-    //End of data
+    /// End of data
     pub end: usize,
-    //Mmap total len
+    /// Mmap total len
     pub len: usize
 }
 
@@ -38,7 +36,7 @@ impl Mmap {
         &mut self.inner[..self.end]
     }
 
-    //Copies data to mmap and modifies data's end cursor.
+    /// Copies data to mmap and modifies data's end cursor.
     fn write(&mut self, data: &[u8]) -> Result<(), failure::Error> {
         if data.len() > self.len {
             return Err(failure::err_msg("Unexpected write beyond mmap's backend capacity. This is a rustbreak's bug"));
@@ -52,11 +50,12 @@ impl Mmap {
         self.inner.flush()
     }
 
-    //Increases mmap size by max(old_size*2, new_size)
-    //Note that it doesn't copy original data
+    /// Increases mmap size by max(old_size*2, new_size).
+    ///
+    /// Note that it doesn't copy original data
     fn resize_no_copy(&mut self, new_size: usize) -> io::Result<()> {
         let len = cmp::max(self.len + self.len, new_size);
-        //Make sure we don't discard old mmap before creating new one;
+        // Make sure we don't discard old mmap before creating new one;
         let new_mmap = Self::new(len)?;
         *self = new_mmap;
         Ok(())
@@ -80,12 +79,12 @@ pub struct MmapStorage {
 }
 
 impl MmapStorage {
-    ///Creates new storage with 1024 bytes
+    /// Creates new storage with 1024 bytes.
     pub fn new() -> error::Result<Self> {
         Self::with_size(1024)
     }
 
-    ///Creates new storage with custom size.
+    /// Creates new storage with custom size.
     pub fn with_size(len: usize) -> error::Result<Self> {
         let mmap = Mmap::new(len).context(error::RustbreakErrorKind::Backend)?;
 

src/backend/mod.rs

@@ -2,7 +2,7 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-//! The persistence backends of the Database
+//! The persistence backends of the Database.
 //!
 //! A file is a `Backend` through the `FileBackend`, so is a `Vec<u8>` with a `MemoryBackend`.
 //!
@@ -13,15 +13,15 @@ use failure::ResultExt;
 
 use crate::error;
 
-/// The Backend Trait
+/// The Backend Trait.
 ///
 /// It should always read and save in full the data that it is passed. This means that a write to
 /// the backend followed by a read __must__ return the same dataset.
 pub trait Backend {
-    /// Read the all data from the backend
+    /// Read the all data from the backend.
     fn get_data(&mut self) -> error::Result<Vec<u8>>;
 
-    /// Write the whole slice to the backend
+    /// Write the whole slice to the backend.
     fn put_data(&mut self, data: &[u8]) -> error::Result<()>;
 }
 
@@ -83,7 +83,7 @@ impl Backend for FileBackend {
 }
 
 impl FileBackend {
-    /// Opens a new FileBackend for a given path, will create it if the file doesn't exist.
+    /// Opens a new [`FileBackend`] for a given path, will create it if the file doesn't exist.
     pub fn open<P: AsRef<std::path::Path>>(path: P) -> error::Result<FileBackend> {
         use std::fs::OpenOptions;
 
@@ -92,25 +92,28 @@ impl FileBackend {
         ))
     }
 
-    /// Use an already open File as the backend
+    /// Use an already open [`File`](std::fs::File) as the backend.
+    #[must_use]
     pub fn from_file(file: std::fs::File) -> FileBackend {
         FileBackend(file)
     }
 
-    /// Return the inner File
+    /// Return the inner File.
+    #[must_use]
     pub fn into_inner(self) -> std::fs::File {
         self.0
     }
 }
 
-/// An in memory backend
+/// An in memory backend.
 ///
-/// It is backed by a `Vec<u8>`
+/// It is backed by a byte vector (`Vec<u8>`).
 #[derive(Debug, Default)]
 pub struct MemoryBackend(Vec<u8>);
 
 impl MemoryBackend {
-    /// Construct a new Memory Database
+    /// Construct a new Memory Database.
+    #[must_use]
     pub fn new() -> MemoryBackend {
         MemoryBackend::default()
     }

src/deser.rs

@@ -78,7 +78,6 @@ pub trait DeSerializer<T: Serialize + DeserializeOwned> : ::std::default::Defaul
 mod ron {
     use std::io::Read;
 
-    use failure;
     use serde::Serialize;
     use serde::de::DeserializeOwned;
     use failure::ResultExt;
@@ -109,7 +108,6 @@ mod ron {
 mod yaml {
     use std::io::Read;
 
-    use failure;
     use serde_yaml::{to_string as to_yaml_string, from_reader as from_yaml_string};
     use serde::Serialize;
     use serde::de::DeserializeOwned;
@@ -138,7 +136,6 @@ mod yaml {
 mod bincode {
     use std::io::Read;
 
-    use failure;
     use bincode::{deserialize_from, serialize};
     use serde::Serialize;
     use serde::de::DeserializeOwned;

src/error.rs

@@ -7,6 +7,7 @@ use failure::{Context, Fail, Backtrace};
 
 /// The different kinds of errors that can be returned
 #[derive(Copy, Clone, Eq, PartialEq, Debug, Fail)]
+#[non_exhaustive]
 pub enum RustbreakErrorKind {
     /// A context error when a serialization failed
     #[fail(display = "Could not serialize the value")]
@@ -23,10 +24,6 @@ pub enum RustbreakErrorKind {
     /// If `Database::write_safe` is used and the closure panics, this error is returned
     #[fail(display = "The write operation paniced but got caught")]
     WritePanic,
-    /// This variant should never be used. It is meant to keep this enum forward compatible.
-    #[doc(hidden)]
-    #[fail(display = "You have found a secret message, please report it to the Rustbreak maintainer")]
-    __Nonexhaustive,
 }
 
 /// The main error type that gets returned for errors that happen while interacting with a

src/lib.rs

@@ -51,7 +51,7 @@
 //! saves, so that the old database contents won't be lost when panicing during the save. It
 //! should therefore be preferred to a [`FileDatabase`].
 //!
-//! Using the `with_deser` and `with_backend` one can switch between the representations one needs.
+//! Using the [`Database::with_deser`] and [`Database::with_backend`] one can switch between the representations one needs.
 //! Even at runtime! However this is only useful in a few scenarios.
 //!
 //! If you have any questions feel free to ask at the main [repo][repo].
@@ -121,7 +121,7 @@
 //! ## Error Handling
 //!
 //! Handling errors in Rustbreak is straightforward. Every `Result` has as its fail case as
-//! `error::RustbreakError`. This means that you can now either continue bubbling up said error
+//! [`error::RustbreakError`]. This means that you can now either continue bubbling up said error
 //! case, or handle it yourself.
 //!
 //! You can simply call its `.kind()` method, giving you all the information you need to continue.
@@ -145,8 +145,8 @@
 //!
 //! ## Panics
 //!
-//! This Database implementation uses `RwLock` and `Mutex` under the hood. If either the closures
-//! given to `Database::write` or any of the Backend implementation methods panic the respective
+//! This Database implementation uses [`RwLock`] and [`Mutex`] under the hood. If either the closures
+//! given to [`Database::write`] or any of the Backend implementation methods panic the respective
 //! objects are then poisoned. This means that you *cannot panic* under any circumstances in your
 //! closures or custom backends.
 //!
@@ -208,13 +208,13 @@ use crate::backend::{Backend, MemoryBackend, FileBackend, PathBackend};
 #[cfg(feature = "mmap")]
 use crate::backend::MmapStorage;
 
-/// The Central Database to RustBreak
+/// The Central Database to Rustbreak.
 ///
 /// It has 3 Type Generics:
 ///
-/// - Data: Is the Data, you must specify this
-/// - Back: The storage backend.
-/// - DeSer: The Serializer/Deserializer or short DeSer. Check the `deser` module for other
+/// - `Data`: Is the Data, you must specify this
+/// - `Back`: The storage backend.
+/// - `DeSer`: The Serializer/Deserializer or short DeSer. Check the [`deser`] module for other
 ///     strategies.
 ///
 /// # Panics
@@ -236,7 +236,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         Back: Backend,
         DeSer: DeSerializer<Data> + Send + Sync + Clone
 {
-    /// Write lock the database and get write access to the `Data` container
+    /// Write lock the database and get write access to the `Data` container.
     ///
     /// This gives you an exclusive lock on the memory object. Trying to open the database in
     /// writing will block if it is currently being written to.
@@ -290,7 +290,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         Ok(task(&mut lock))
     }
 
-    /// Write lock the database and get write access to the `Data` container in a safe way
+    /// Write lock the database and get write access to the `Data` container in a safe way.
     ///
     /// This gives you an exclusive lock on the memory object. Trying to open the database in
     /// writing will block if it is currently being written to.
@@ -303,7 +303,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
     /// for panic safety.
     ///
     /// You should read the documentation about this:
-    /// [UnwindSafe](https://doc.rust-lang.org/std/panic/trait.UnwindSafe.html)
+    /// [`UnwindSafe`](https://doc.rust-lang.org/std/panic/trait.UnwindSafe.html)
     ///
     /// # Panics
     ///
@@ -376,7 +376,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         Ok(())
     }
 
-    /// Read lock the database and get read access to the `Data` container
+    /// Read lock the database and get read access to the `Data` container.
     ///
     /// This gives you a read-only lock on the database. You can have as many readers in parallel
     /// as you wish.
@@ -399,7 +399,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         Ok(task(&mut lock))
     }
 
-    /// Read lock the database and get access to the underlying struct
+    /// Read lock the database and get access to the underlying struct.
     ///
     /// This gives you access to the underlying struct, allowing for simple read
     /// only operations on it.
@@ -440,7 +440,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         self.data.read().map_err(|_| error::RustbreakErrorKind::Poison.into())
     }
 
-    /// Write lock the database and get access to the underlying struct
+    /// Write lock the database and get access to the underlying struct.
     ///
     /// This gives you access to the underlying struct, allowing you to modify it.
     ///
@@ -514,7 +514,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         Ok(data_write_lock)
     }
 
-    /// Load the Data from the backend
+    /// Load the data from the backend.
     pub fn load(&self) -> error::Result<()> {
         self.load_get_data_lock().map(|_| ())
     }
@@ -532,15 +532,15 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         Ok(())
     }
 
-    /// Flush the data structure to the backend
+    /// Flush the data structure to the backend.
     pub fn save(&self) -> error::Result<()> {
         let data = self.data.read().map_err(|_| error::RustbreakErrorKind::Poison)?;
         self.save_data_locked(data)
     }
 
-    /// Get a clone of the data as it is in memory right now
+    /// Get a clone of the data as it is in memory right now.
     ///
-    /// To make sure you have the latest data, call this method with `load` true
+    /// To make sure you have the latest data, call this method with `load` true.
     pub fn get_data(&self, load: bool) -> error::Result<Data> {
         let data = if load {
             self.load_get_data_lock()?
@@ -550,7 +550,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         Ok(data.clone())
     }
 
-    /// Puts the data as is into memory
+    /// Puts the data as is into memory.
     ///
     /// To save the data afterwards, call with `save` true.
     pub fn put_data(&self, new_data: Data, save: bool) -> error::Result<()> {
@@ -563,7 +563,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         }
     }
 
-    /// Create a database from its constituents
+    /// Create a database from its constituents.
     pub fn from_parts(data: Data, backend: Back, deser: DeSer) -> Database<Data, Back, DeSer> {
         Database {
             data: RwLock::new(data),
@@ -572,7 +572,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         }
     }
 
-    /// Break a database into its individual parts
+    /// Break a database into its individual parts.
     pub fn into_inner(self) -> error::Result<(Data, Back, DeSer)> {
         Ok((self.data.into_inner().map_err(|_| error::RustbreakErrorKind::Poison)?,
             self.backend.into_inner().map_err(|_| error::RustbreakErrorKind::Poison)?,
@@ -633,7 +633,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
     }
 }
 
-/// A database backed by a file
+/// A database backed by a file.
 pub type FileDatabase<D, DS> = Database<D, FileBackend, DS>;
 
 impl<Data, DeSer> Database<Data, FileBackend, DeSer>
@@ -641,7 +641,7 @@ impl<Data, DeSer> Database<Data, FileBackend, DeSer>
         Data: Serialize + DeserializeOwned + Clone + Send,
         DeSer: DeSerializer<Data> + Send + Sync + Clone
 {
-    /// Create new FileDatabase from Path
+    /// Create new [`FileDatabase`] from the file at [`Path`](std::path::Path).
     pub fn from_path<S>(path: S, data: Data)
         -> error::Result<FileDatabase<Data, DeSer>>
         where S: AsRef<std::path::Path>
@@ -655,7 +655,7 @@ impl<Data, DeSer> Database<Data, FileBackend, DeSer>
         })
     }
 
-    /// Create new FileDatabase from a file
+    /// Create new [`FileDatabase`] from a file.
     pub fn from_file(file: ::std::fs::File, data: Data) -> error::Result<FileDatabase<Data, DeSer>>
     {
         let backend = FileBackend::from_file(file);
@@ -694,7 +694,7 @@ impl<Data, DeSer> Database<Data, PathBackend, DeSer>
     }
 }
 
-/// A database backed by a `Vec<u8>`
+/// A database backed by a byte vector (`Vec<u8>`).
 pub type MemoryDatabase<D, DS> = Database<D, MemoryBackend, DS>;
 
 impl<Data, DeSer> Database<Data, MemoryBackend, DeSer>
@@ -702,7 +702,7 @@ impl<Data, DeSer> Database<Data, MemoryBackend, DeSer>
         Data: Serialize + DeserializeOwned + Clone + Send,
         DeSer: DeSerializer<Data> + Send + Sync + Clone
 {
-    /// Create new FileDatabase from Path
+    /// Create new in-memory database.
     pub fn memory(data: Data) -> error::Result<MemoryDatabase<Data, DeSer>> {
         let backend = MemoryBackend::new();
 
@@ -724,7 +724,7 @@ impl<Data, DeSer> Database<Data, MmapStorage, DeSer>
         Data: Serialize + DeserializeOwned + Clone + Send,
         DeSer: DeSerializer<Data> + Send + Sync + Clone
 {
-    /// Create new MmapDatabase.
+    /// Create new [`MmapDatabase`].
     pub fn mmap(data: Data) -> error::Result<MmapDatabase<Data, DeSer>> {
         let backend = MmapStorage::new()?;
 
@@ -735,7 +735,7 @@ impl<Data, DeSer> Database<Data, MmapStorage, DeSer>
         })
     }
 
-    /// Create new MmapDatabase with specified initial size.
+    /// Create new [`MmapDatabase`] with specified initial size.
     pub fn mmap_with_size(data: Data, size: usize) -> error::Result<MmapDatabase<Data, DeSer>> {
         let backend = MmapStorage::with_size(size)?;
 
@@ -748,7 +748,7 @@ impl<Data, DeSer> Database<Data, MmapStorage, DeSer>
 }
 
 impl<Data, Back, DeSer> Database<Data, Back, DeSer> {
-    /// Exchanges the DeSerialization strategy with the new one
+    /// Exchanges the `DeSerialization` strategy with the new one.
     pub fn with_deser<T>(self, deser: T) -> Database<Data, Back, T>
     {
         Database {
@@ -760,7 +760,7 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer> {
 }
 
 impl<Data, Back, DeSer> Database<Data, Back, DeSer> {
-    /// Exchanges the Backend with the new one
+    /// Exchanges the `Backend` with the new one.
     ///
     /// The new backend does not necessarily have the latest data saved to it, so a `.save` should
     /// be called to make sure that it is saved.
@@ -780,9 +780,9 @@ impl<Data, Back, DeSer> Database<Data, Back, DeSer>
         Back: Backend,
         DeSer: DeSerializer<Data> + Send + Sync + Clone
 {
-    /// Converts from one data type to another
+    /// Converts from one data type to another.
     ///
-    /// This method is useful to migrate from one datatype to another
+    /// This method is useful to migrate from one datatype to another.
     pub fn convert_data<C, OutputData>(self, convert: C)
         -> error::Result<Database<OutputData, Back, DeSer>>
         where