From 63fe77ec6d2ae9950d48cd60fdf59e8b2498a16b Mon Sep 17 00:00:00 2001 From: niluxv Date: Thu, 2 Jul 2020 14:43:54 +0200 Subject: [PATCH] Fix clippy lints and improve docs --- src/backend/mmap.rs | 19 +++++++------- src/backend/mod.rs | 23 +++++++++------- src/deser.rs | 3 --- src/error.rs | 5 +--- src/lib.rs | 64 ++++++++++++++++++++++----------------------- 5 files changed, 55 insertions(+), 59 deletions(-) diff --git a/src/backend/mmap.rs b/src/backend/mmap.rs index dd35fd3..bc0359f 100644 --- a/src/backend/mmap.rs +++ b/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::with_size(1024) } - ///Creates new storage with custom size. + /// Creates new storage with custom size. pub fn with_size(len: usize) -> error::Result { let mmap = Mmap::new(len).context(error::RustbreakErrorKind::Backend)?; diff --git a/src/backend/mod.rs b/src/backend/mod.rs index 46adda4..3bc0e0f 100644 --- a/src/backend/mod.rs +++ b/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` 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>; - /// 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>(path: P) -> error::Result { 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` +/// It is backed by a byte vector (`Vec`). #[derive(Debug, Default)] pub struct MemoryBackend(Vec); impl MemoryBackend { - /// Construct a new Memory Database + /// Construct a new Memory Database. + #[must_use] pub fn new() -> MemoryBackend { MemoryBackend::default() } diff --git a/src/deser.rs b/src/deser.rs index a1b9275..86f08bf 100644 --- a/src/deser.rs +++ b/src/deser.rs @@ -78,7 +78,6 @@ pub trait DeSerializer : ::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; diff --git a/src/error.rs b/src/error.rs index 2ef2e9c..36680a6 100644 --- a/src/error.rs +++ b/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 diff --git a/src/lib.rs b/src/lib.rs index 4703e9e..0bec98c 100644 --- a/src/lib.rs +++ b/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 Database Back: Backend, DeSer: DeSerializer + 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 Database 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 Database /// 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 Database 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 Database 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 Database 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 Database 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 Database 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 { let data = if load { self.load_get_data_lock()? @@ -550,7 +550,7 @@ impl Database 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 Database } } - /// Create a database from its constituents + /// Create a database from its constituents. pub fn from_parts(data: Data, backend: Back, deser: DeSer) -> Database { Database { data: RwLock::new(data), @@ -572,7 +572,7 @@ impl Database } } - /// 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 Database } } -/// A database backed by a file +/// A database backed by a file. pub type FileDatabase = Database; impl Database @@ -641,7 +641,7 @@ impl Database Data: Serialize + DeserializeOwned + Clone + Send, DeSer: DeSerializer + Send + Sync + Clone { - /// Create new FileDatabase from Path + /// Create new [`FileDatabase`] from the file at [`Path`](std::path::Path). pub fn from_path(path: S, data: Data) -> error::Result> where S: AsRef @@ -655,7 +655,7 @@ impl Database }) } - /// Create new FileDatabase from a file + /// Create new [`FileDatabase`] from a file. pub fn from_file(file: ::std::fs::File, data: Data) -> error::Result> { let backend = FileBackend::from_file(file); @@ -694,7 +694,7 @@ impl Database } } -/// A database backed by a `Vec` +/// A database backed by a byte vector (`Vec`). pub type MemoryDatabase = Database; impl Database @@ -702,7 +702,7 @@ impl Database Data: Serialize + DeserializeOwned + Clone + Send, DeSer: DeSerializer + Send + Sync + Clone { - /// Create new FileDatabase from Path + /// Create new in-memory database. pub fn memory(data: Data) -> error::Result> { let backend = MemoryBackend::new(); @@ -724,7 +724,7 @@ impl Database Data: Serialize + DeserializeOwned + Clone + Send, DeSer: DeSerializer + Send + Sync + Clone { - /// Create new MmapDatabase. + /// Create new [`MmapDatabase`]. pub fn mmap(data: Data) -> error::Result> { let backend = MmapStorage::new()?; @@ -735,7 +735,7 @@ impl Database }) } - /// 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> { let backend = MmapStorage::with_size(size)?; @@ -748,7 +748,7 @@ impl Database } impl Database { - /// Exchanges the DeSerialization strategy with the new one + /// Exchanges the `DeSerialization` strategy with the new one. pub fn with_deser(self, deser: T) -> Database { Database { @@ -760,7 +760,7 @@ impl Database { } impl Database { - /// 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 Database Back: Backend, DeSer: DeSerializer + 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(self, convert: C) -> error::Result> where