docs: examples

Signed-off-by: Adam Perkowski <[email protected]>

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

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")]

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::*;

src/keyfile.rs

@@ -1,10 +1,10 @@
 //! 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 serde::Deserialize;
+use std::path::Path;
 use tokio::fs;
 
 /// keyfile structure
@@ -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")]

src/lib.rs

@@ -1,16 +1,40 @@
 //! 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;
 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(

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,