From d6c1a8ca92fae770884f13b14e15311ca44c133d Mon Sep 17 00:00:00 2001
From: Adam Perkowski <adas1per@protonmail.com>
Date: Sun, 24 Nov 2024 18:59:52 +0100
Subject: [PATCH] docs: examples

Signed-off-by: Adam Perkowski <adas1per@protonmail.com>
---
 Cargo.lock      | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 Cargo.toml      |  3 +++
 src/config.rs   | 15 ++++++++++++---
 src/error.rs    | 10 ----------
 src/keyfile.rs  |  8 ++++----
 src/lib.rs      | 34 +++++++++++++++++++++++++++++++---
 src/verfiles.rs |  4 ++--
 7 files changed, 99 insertions(+), 22 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 3061743..afa9340 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -66,6 +66,28 @@ dependencies = [
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "async-stream"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b5a71a6f37880a80d1d7f19efd781e4b5de42c88f0722cc13bcb6cc2cfe8476"
+dependencies = [
+ "async-stream-impl",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-stream-impl"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7c24de15d275a1ecfd47a380fb4d5ec9bfe0933f309ed5e705b775596a3574d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -808,6 +830,7 @@ dependencies = [
  "serde_json",
  "thiserror",
  "tokio",
+ "tokio-test",
  "toml",
 ]
 
@@ -1338,6 +1361,30 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-stream"
+version = "0.1.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f4e6ce100d0eb49a2734f8c0812bcd324cf357d21810932c5df6b96ef2b86f1"
+dependencies = [
+ "futures-core",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "tokio-test"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2468baabc3311435b55dd935f702f42cd1b8abb7e754fb7dfb16bd36aa88f9f7"
+dependencies = [
+ "async-stream",
+ "bytes",
+ "futures-core",
+ "tokio",
+ "tokio-stream",
+]
+
 [[package]]
 name = "tokio-util"
 version = "0.7.12"
diff --git a/Cargo.toml b/Cargo.toml
index db0dae5..0dc1577 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -37,6 +37,9 @@ thiserror = "2.0.3"
 tokio = { version = "1.41.1", features = ["full"] }
 toml = { version = "0.8.19", features = ["parse", "display"], default-features = false }
 
+[dev-dependencies]
+tokio-test = "0.4.4"
+
 [profile.release]
 lto = "fat"
 codegen-units = 1
diff --git a/src/config.rs b/src/config.rs
index f0bb60f..c60be8f 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -1,6 +1,7 @@
 //! operations on configuration files
-///
-/// see the [example `nvrs.toml`](https://github.com/adamperkowski/nvrs/blob/main/nvrs.toml)
+//!
+//! see the [example `nvrs.toml`](https://github.com/adamperkowski/nvrs/blob/main/nvrs.toml)
+
 use crate::error;
 use serde::{Deserialize, Serialize};
 use std::{
@@ -20,7 +21,7 @@ pub struct Config {
     pub packages: BTreeMap<String, Package>,
 }
 
-/// `__config__` structure
+/// `__config__` table structure
 ///
 /// see the [example `nvrs.toml`](https://github.com/adamperkowski/nvrs/blob/main/nvrs.toml)
 #[derive(Debug, Clone, Deserialize, Serialize)]
@@ -61,6 +62,14 @@ pub struct Package {
 
 impl Package {
     /// global function to get various API-specific agrs for a package
+    ///
+    /// # example
+    /// ```rust,ignore
+    /// // package has `source = "github"` * `github = "adamperkowski/nvrs"` specified
+    /// let args = package.get_api();
+    ///
+    /// assert_eq!(package, ("github", vec!["adamperkowski/nvrs"]))
+    /// ```
     pub fn get_api(&self) -> (String, Vec<String>) {
         let args = match self.source.as_str() {
             #[cfg(feature = "aur")]
diff --git a/src/error.rs b/src/error.rs
index 5b01fbe..65dcb90 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -72,16 +72,6 @@ pub enum Error {
 
 pub type Result<T> = std::result::Result<T, Error>;
 
-/*
-pub fn custom_error(title: &'static str, message: String, exit: bool /*, force: bool*/) {
-    println!("! {}{}", title.red(), message.replace("\n", "\n  "));
-
-    if exit {
-        std::process::exit(1);
-    }
-}
-*/
-
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/src/keyfile.rs b/src/keyfile.rs
index c4bf52c..32b2f3d 100644
--- a/src/keyfile.rs
+++ b/src/keyfile.rs
@@ -1,9 +1,9 @@
 //! operations on keyfiles
-use std::path::Path;
+//!
+//! see the [example `nvrs.toml`](https://github.com/adamperkowski/nvrs/blob/main/nvrs.toml) & [example `keyfile.toml`](https://github.com/adamperkowski/nvrs/blob/main/n_keyfile.toml)
 
-///
-/// see the [example `nvrs.toml`](https://github.com/adamperkowski/nvrs/blob/main/nvrs.toml) & [example `keyfile.toml`](https://github.com/adamperkowski/nvrs/blob/main/n_keyfile.toml)
 use crate::{config, error};
+use std::path::Path;
 use serde::Deserialize;
 use tokio::fs;
 
@@ -31,7 +31,7 @@ struct KeysTable {
 }
 
 impl Keyfile {
-    /// returns the API key for the specified API name (empty string if not found)
+    /// returns API key for the specified API name (empty string if not found)
     pub async fn get_key(&self, api_name: &str) -> String {
         match api_name {
             #[cfg(feature = "github")]
diff --git a/src/lib.rs b/src/lib.rs
index 3bcf59c..beb3de3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,8 +1,14 @@
 //! nvrs - fast new version checker for software releases 🚦🦀
 //!
-//! nvrs is still a WIP<br>
-//! new features & bugfixes are being pushed every day<br>
+//! <div class="warning">
+//!
+//! nvrs is still a WIP
+//!
+//! new features & bugfixes are being pushed every day
+//!
 //! you may encounter some issues. please consider [submitting feedback](https://github.com/adamperkowski/nvrs/issues/new/choose) if you do.
+//!
+//! </div>
 
 pub mod api;
 pub mod config;
@@ -10,7 +16,25 @@ pub mod error;
 pub mod keyfile;
 pub mod verfiles;
 
-/// example "core" vars structure
+/// "core" vars structure
+///
+/// # example usage
+/// ```rust
+/// # tokio_test::block_on(async {
+/// use nvrs::*;
+///
+/// let config = config::load(None).await.unwrap();
+/// let verfiles = verfiles::load(config.0.__config__.clone()).await.unwrap();
+/// let keyfile = keyfile::load(config.0.__config__.clone()).await.unwrap();
+///
+/// Core {
+///     config: config.0,
+///     verfiles,
+///     client: reqwest::Client::new(),
+///     keyfile,
+/// };
+/// # })
+/// ```
 pub struct Core {
     pub config: config::Config,
     pub verfiles: (verfiles::Verfile, verfiles::Verfile),
@@ -21,10 +45,14 @@ pub struct Core {
 /// an asynchronous function that package's source and gets the latest release
 /// # example usage
 /// ```rust,ignore
+/// # tokio_test::block_on(async {
+/// use nvrs::run_source;
+///
 /// let package_name = "nvrs".to_string();
 /// let client = reqwest::Client::new();
 ///
 /// run_source((package_name, package), client).await;
+/// # })
 /// ```
 /// see [crate::config::Package] for `package`
 pub async fn run_source(
diff --git a/src/verfiles.rs b/src/verfiles.rs
index 89f7f37..7b8ebe2 100644
--- a/src/verfiles.rs
+++ b/src/verfiles.rs
@@ -40,7 +40,7 @@ pub struct Verfile {
 }
 
 // TODO: move `load` & `save` logic into `config.rs` maybe
-/// asynchronous function for loading the verfiles
+/// load the verfiles specified in [crate::config::ConfigTable]
 pub async fn load(config_table: Option<config::ConfigTable>) -> error::Result<(Verfile, Verfile)> {
     if config_table.is_none() {
         return Err(error::Error::NoConfigTable);
@@ -61,7 +61,7 @@ pub async fn load(config_table: Option<config::ConfigTable>) -> error::Result<(V
     }
 }
 
-/// asynchronous function for saving changes to the verfiles
+/// save changes to the verfiles
 pub async fn save(
     verfile: Verfile,
     is_oldver: bool,