Merge pull request #7 from brummer-simon/document_everything

Add documentation

Author: brummer-simon

examples/async_usage/src/main.rs

@@ -1,10 +1,10 @@
-use std::str::FromStr;
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
 //
 // Author: Simon Brummer ([email protected])
 
+use std::str::FromStr;
 use std::thread::sleep;
 use std::time::Duration;
 

rustfmt.toml

@@ -9,8 +9,6 @@ wrap_comments = true
 normalize_comments = true
 
 # Import related
-reorder_imports = true
-group_imports = "StdExternalCrate"
 imports_granularity = "Module"
 
 # Warning related

src/async_target.rs

@@ -4,22 +4,29 @@
 //
 // Author: Simon Brummer ([email protected])
 
-use std::thread::{spawn, JoinHandle};
-use std::time::Duration;
+//! Module contains utilities for asynchronous, iterative "Target" reachability checking.
+//!
+//! # Notes
+//! Requires crate to be configured with feature "async".
 
+use super::{CheckTargetError, Status, Target};
 use futures::future::{join, join_all, BoxFuture, FutureExt};
+use std::thread::{spawn, JoinHandle};
+use std::time::Duration;
 use tokio::runtime::{self};
 use tokio::select;
-use tokio::sync::watch::{
-    Receiver, Sender, {self},
-};
+use tokio::sync::watch::{self, Receiver, Sender};
 use tokio::task::{self};
 use tokio::time::{self};
 
-use crate::{CheckTargetError, Status, Target};
-
+/// Alias on [Status] to distinct between status of previous availability
+/// check and the current availability check
 pub type OldStatus = Status;
 
+/// Struct storing all data used during asynchronous execution.
+///
+/// For async check execution, wrap the instances of [Target] in [AsyncTarget] and hand them to
+/// [AsyncTargetExecutor::start].
 pub struct AsyncTarget<'a> {
     target: Box<dyn Target + Send + 'a>,
     check_handler: Box<dyn FnMut(&dyn Target, Status, OldStatus, Option<CheckTargetError>) + Send + 'a>,
@@ -28,6 +35,15 @@ pub struct AsyncTarget<'a> {
 }
 
 impl<'a> AsyncTarget<'a> {
+    /// Construct an [AsyncTarget]. For more convenience use [AsyncTarget::from] instead.
+    ///
+    /// # Arguments
+    /// * target: trait object implementing [Target] to use in periodic checks.
+    /// * check_handler: Function to call with the results of [Target::check_availability].
+    /// * check_interval: time [Duration] between periodic availability checks.
+    ///
+    /// # Returns
+    /// Instance of [AsyncTarget].
     pub fn new(
         target: Box<dyn Target + Send + 'a>,
         check_handler: Box<dyn FnMut(&dyn Target, Status, OldStatus, Option<CheckTargetError>) + Send + 'a>,
@@ -47,23 +63,57 @@ where
     T: Target + Send + 'a,
     U: FnMut(&dyn Target, Status, OldStatus, Option<CheckTargetError>) + Send + 'a,
 {
+    /// Build a [AsyncTarget] from a Target, a function to be executed with the results of
+    /// an availability check and a time interval an availability check occurs.
+    ///
+    /// # Example
+    /// See Example in [AsyncTargetExecutor::start]
     fn from(pieces: (T, U, Duration)) -> AsyncTarget<'a> {
         let (target, check_handler, check_interval) = pieces;
         AsyncTarget::new(Box::from(target), Box::from(check_handler), check_interval)
     }
 }
 
+/// Async target check executor used to check the availability of a given number of [AsyncTarget]s.
 pub struct AsyncTargetExecutor {
+    /// Optional threadhandle and synchronization channel to executing runtime.
     worker: Option<(JoinHandle<()>, Sender<()>)>,
 }
 
 impl AsyncTargetExecutor {
+    /// Construct a new [AsyncTargetExecutor]
     pub fn new() -> Self {
         AsyncTargetExecutor {
             worker: None,
         }
     }
 
+    /// Start periodic availability checks for all given targets
+    ///
+    /// Each targets execution behavior is configured during [AsyncTarget] construction.
+    ///
+    /// # Arguments
+    /// * targets: a vector of [AsyncTarget]s, those availability should be check periodically.
+    ///
+    /// # Example
+    /// ```
+    /// # use std::{str::FromStr, thread::sleep, time::Duration};
+    /// # use reachable::*;
+    ///
+    /// // Setup AsyncTarget
+    /// let target = IcmpTarget::from_str("127.0.0.1").unwrap();
+    /// let check_handler = |_: &dyn Target, _: Status, _: OldStatus, _: Option<CheckTargetError>| {
+    ///    // Handle check results
+    /// };
+    /// let check_interval = Duration::from_secs(1);
+    /// let async_target = AsyncTarget::from((target, check_handler, check_interval));
+    ///
+    /// // Setup AsyncTargetExecutor and let it run for 1s
+    /// let mut exec = AsyncTargetExecutor::new();
+    /// exec.start(vec![async_target]);
+    /// sleep(Duration::from_secs(1));
+    /// exec.stop();
+    /// ```
     pub fn start(&mut self, targets: Vec<AsyncTarget<'static>>) {
         if self.worker.is_none() {
             // Setup teardown mechanism and construct runtime
@@ -92,6 +142,7 @@ impl AsyncTargetExecutor {
         }
     }
 
+    /// Stop asynchronous processing started with [AsyncTargetExecutor::start] gracefully.
     pub fn stop(&mut self) {
         if let Some((handle, teardown_send)) = self.worker.take() {
             // Signal all async tasks to terminate and wait until runtime thread stopped.

src/error.rs

@@ -4,21 +4,29 @@
 //
 // Author: Simon Brummer ([email protected])
 
+//! Module containing all custom error types. All type shall implement [Error].
+
+// Imports
 use std::error::Error;
 use std::fmt::{self};
 use std::io::{self};
 use std::num::{self};
 
-type ErrorMessage = &'static str;
+// Documentation imports
+#[cfg(doc)]
+use super::Target;
+
+/// Alias for preallocated error messages
+pub type ErrorMessage = &'static str;
 
-// ParseTargetError
+/// Custom error type for a failed attempt to parse something into a [Target].
 #[derive(Debug)]
 pub enum ParseTargetError {
     /// ParseTargetError containing a Message
     Message(ErrorMessage),
-    /// ParseTargetError containing a Message and a ParseIntError
+    /// ParseTargetError containing a Message and a [num::ParseIntError]
     ParseIntError(ErrorMessage, num::ParseIntError),
-    /// ParseTargetError containing a Message and a trait object implementing Error
+    /// ParseTargetError containing a Message and a trait object implementing [Error]
     GenericError(ErrorMessage, Box<dyn Error>),
 }
 
@@ -73,14 +81,14 @@ impl From<Box<dyn Error>> for ParseTargetError {
     }
 }
 
-// ResolveTargetError
+/// Custom error type for a failed attempt to resolve a [Target].
 #[derive(Debug)]
 pub enum ResolveTargetError {
     /// ResolveTargetError containing a Message
     Message(ErrorMessage),
-    /// ResolveTargetError containing a Message and an io::Error
+    /// ResolveTargetError containing a Message and an [io::Error]
     IoError(ErrorMessage, io::Error),
-    /// CheckTargetError containing a Message and a trait object implementing Error
+    /// ResolveTargetError containing a Message and a trait object implementing [Error]
     GenericError(ErrorMessage, Box<dyn Error>),
 }
 
@@ -141,14 +149,14 @@ impl From<Box<dyn Error>> for ResolveTargetError {
     }
 }
 
-// TargetCheckError
+/// Custom error type for a failed attempt to check the availability of a [Target].
 #[derive(Debug)]
 pub enum CheckTargetError {
     /// CheckTargetError containing a Message
     Message(ErrorMessage),
-    /// CheckTargetError containing a Message and a ResolveTargetError
+    /// CheckTargetError containing a Message and a [ResolveTargetError]
     ResolveTargetError(ErrorMessage, ResolveTargetError),
-    /// CheckTargetError containing a Message and a trait object implementing Error
+    /// CheckTargetError containing a Message and a trait object implementing [Error]
     GenericError(ErrorMessage, Box<dyn Error>),
 }
 

src/lib.rs

@@ -4,17 +4,27 @@
 //
 // Author: Simon Brummer ([email protected])
 
-mod error;
-pub use error::{CheckTargetError, ParseTargetError, ResolveTargetError};
-
-mod resolve_policy;
-pub use resolve_policy::ResolvePolicy;
+//! Reachable, check if a Target is currently available or not.
+//!
+//! A "Target" is everything that implements the Target trait, used to
+//! check if, a resource is currently available. This crate offers a ICMP and TCP based Target
+//! usable to check, if a computer is available over the network.
+//!
+//! Additionally this crate contains asynchronous utilities to execute these checks regularly
+//! within a given time interval.
 
-mod target;
-pub use target::{IcmpTarget, Status, Target, TcpTarget};
+// Modules
+pub mod error;
+pub mod resolve_policy;
+pub mod target;
 
 #[cfg(feature = "async")]
-mod async_target;
+pub mod async_target;
+
+// Re-exports
+pub use error::{CheckTargetError, ParseTargetError, ResolveTargetError};
+pub use resolve_policy::ResolvePolicy;
+pub use target::{Fqhn, IcmpTarget, Port, Status, Target, TcpTarget};
 
 #[cfg(feature = "async")]
 pub use async_target::{AsyncTarget, AsyncTargetExecutor, OldStatus};

src/resolve_policy.rs

@@ -4,23 +4,56 @@
 //
 // Author: Simon Brummer ([email protected])
 
-use std::net::IpAddr;
+//! Module containing everything related network name resolution and filtering
+//! of the resolved IP addresses.
 
+// Imports
+use super::ResolveTargetError;
 use dns_lookup::lookup_host;
+use std::net::IpAddr;
 
-use super::ResolveTargetError;
+// Documentation imports
+#[cfg(doc)]
+use super::{IcmpTarget, TcpTarget};
 
+/// A ResolvePolicy allows control over IP address resolution of network targets
+/// like [IcmpTarget] and [TcpTarget].
 #[derive(PartialEq, Debug)]
 pub enum ResolvePolicy {
-    /// Resolve FQHN IP version agnostic
+    /// Resolve use all IP address versions
     Agnostic,
-    /// Resolve FQHN to IPv4 addresses only
+    /// Resolve to IPv4 addresses only
     ResolveToIPv4,
-    /// Resolve FQHN to IPv6 addresses only
+    /// Resolve to IPv6 addresses only
     ResolveToIPv6,
 }
 
 impl ResolvePolicy {
+    /// Resolve given "fully qualified domain name" (fancy name for a hostname or ip address)
+    /// to a series of ip addresses associated with given fqhn.
+    ///
+    /// # Arguments
+    /// * fqhn: string containing "fully qualified domain name" e.g. "::1", "localhost".
+    ///
+    /// # Returns
+    /// * On success, vector containing all ip addresses the fqhn resolved to.
+    /// * On failure, a [ResolveTargetError]. Either failed the name resolution itself or all
+    ///   addresses were filtered out according to [ResolvePolicy].
+    ///
+    /// # Example
+    /// ```
+    /// # use std::net::{IpAddr, Ipv4Addr};
+    /// # use reachable::ResolvePolicy;
+    ///
+    /// // FQHN was resolved
+    /// assert_eq!(
+    ///     ResolvePolicy::Agnostic.resolve("127.0.0.1").unwrap(),
+    ///     vec![IpAddr::V4(Ipv4Addr::LOCALHOST)]
+    /// );
+    ///
+    /// // FQHN was resolved, but all Addresses were filtered
+    /// assert_eq!(ResolvePolicy::ResolveToIPv6.resolve("127.0.0.1").is_err(), true);
+    /// ```
     pub fn resolve(&self, fqhn: &str) -> Result<Vec<IpAddr>, ResolveTargetError> {
         let mut addrs = lookup_host(fqhn)?;