Merge pull request #17 from johanhelsing/rustdocs-for-everything

Rustdocs for everything

README.md

@@ -9,22 +9,28 @@ bevy\_pkv is a cross-platform persistent key value store for rust apps.
 
 Use it for storing things like settings, save games etc.
 
-Currently, it does not depend on bevy, so it may be used in other games/apps as well.
+Currently, the Bevy dependency is optional, so it may be used in other games/apps as well.
 
-## Usage
+## Usage with Bevy
 
 Add a store resource to your app
 
-```rust
+```rust no_run
+use bevy::prelude::*;
+use bevy_pkv::PkvStore;
+
+fn main() {
 App::new()
     .add_plugins(DefaultPlugins)
     .insert_resource(PkvStore::new("FooCompany", "BarGame"))
+    // ...insert systems etc.
     .run();
+}
 ```
 
 This will create or load a store in the appropriate location for your system, and make it available to bevy systems:
 
-```rust
+```rust ignore
 fn setup(mut pkv: ResMut<PkvStore>) {
     if let Ok(username) = pkv.get::<String>("username") {
         info!("Welcome back {username}");
@@ -41,7 +47,7 @@ fn setup(mut pkv: ResMut<PkvStore>) {
 
 Using your own types implementing `serde::Serialize` and `Deserialize`:
 
-```rust
+```rust ignore
 #[derive(Serialize, Deserialize)]
 struct User {
     name: String,
@@ -61,6 +67,14 @@ fn setup(mut pkv: ResMut<PkvStore>) {
 
 See the [examples](./examples) for further usage
 
+## Usage without Bevy
+
+Disable the default features when adding the dependency:
+
+```toml
+bevy_pkv = {version = 0.7, default-features = false}
+```
+
 ## Implementation details
 
 ### Native

src/lib.rs

@@ -1,3 +1,6 @@
+#![warn(missing_docs)]
+#![doc = include_str!("../README.md")]
+
 use serde::{de::DeserializeOwned, Serialize};
 
 trait StoreImpl {
@@ -37,6 +40,10 @@ pub struct PkvStore {
 }
 
 impl PkvStore {
+    /// Creates or opens a pkv store
+    ///
+    /// The given `organization` and `application` are used to create a backing file
+    /// in a corresponding location on the users device. Usually within the home or user folder
     pub fn new(organization: &str, application: &str) -> Self {
         let config = StoreConfig {
             qualifier: None,
@@ -46,6 +53,11 @@ impl PkvStore {
         Self::new_from_config(&config)
     }
 
+    /// Creates or opens a pkv store
+    ///
+    /// Like [`PkvStore::new`], but also provide a qualifier.
+    /// Some operating systems use the qualifier as part of the path to the store.
+    /// The qualifier is usually "com", "org" etc.
     pub fn new_with_qualifier(qualifier: &str, organization: &str, application: &str) -> Self {
         let config = StoreConfig {
             qualifier: Some(qualifier.to_string()),

src/sled_store.rs

@@ -10,20 +10,27 @@ pub struct SledStore {
 
 pub use SledStore as InnerStore;
 
+/// Errors that can occur during `PkvStore::get`
 #[derive(thiserror::Error, Debug)]
 pub enum GetError {
+    /// An internal error from the sled crate
     #[error("Sled error")]
     Sled(#[from] sled::Error),
+    /// Error when deserializing the value
     #[error("MessagePack deserialization error")]
     MessagePack(#[from] rmp_serde::decode::Error),
+    /// The value for the given key was not found
     #[error("No value found for the given key")]
     NotFound,
 }
 
+/// Errors that can occur during `PkvStore::set`
 #[derive(thiserror::Error, Debug)]
 pub enum SetError {
+    /// An internal error from the sled crate
     #[error("Sled error")]
     Sled(#[from] sled::Error),
+    /// Error when serializing the value
     #[error("MessagePack serialization error")]
     MessagePack(#[from] rmp_serde::encode::Error),
 }