Merge pull request #47 from Deedasmi/master

Initial lib documentation.

Author: Deedasmi

inquisitor_lib/src/lib.rs

@@ -1,3 +1,6 @@
+//! This library is intended for use in both the Inquisitor Agent and the Inquisitor Receptor.
+//! Plugin authors must implement the plugin trait for their desired platform, but they
+//! may also make use of several convience functions included in this library.
 #[macro_use]
 extern crate serde_derive;
 extern crate serde;
@@ -19,7 +22,8 @@ use std::collections::HashMap;
 use std::path::PathBuf;
 use std::time::{SystemTime, UNIX_EPOCH};
 
-
+/// This struct is for communication between agent and receptor.
+/// Plugins should not use this directly
 #[derive(Serialize, Deserialize, Debug)]
 pub struct Status {
 	pub sender:      String,
@@ -28,13 +32,18 @@ pub struct Status {
 	pub plugin_name: String
 }
 
+/// A utility function that returns the current timestamp in seconds
 pub fn current_ts() -> i64 {
 	SystemTime::now()
 		.duration_since(UNIX_EPOCH)
 		.expect("Error getting system time !?")
 		.as_secs() as i64
 }
 
+/// A utility function that returns a deserialized object from a configuration file.
+/// Plugins should use this instead of manipulating their own configuration file
+/// 
+/// # TODO examples
 pub fn read_cfg<ConfigT>(cfg_file_path: &PathBuf) -> Result<ConfigT, String>
 where
 	ConfigT: DeserializeOwned
@@ -45,11 +54,15 @@ where
 	Ok(cfg)
 }
 
+/// This trait is required by agent plugins
 pub trait AgentPlugin {
+	/// Returns the plugin's name. Sent to the server to tag plugin messages
 	fn name(&self) -> &'static str;
-
+	/// This is the 'worker' function, and will be called when the ready fucntion returns true.
+	/// Currently this requires plugins to return a string.
+	/// An `Ok` will be sent to the server, while currently an `Err` is output to the terminal on the agent
 	fn gather(&mut self) -> Result<String, String>;
-
+	/// This function tells the agent if the plugin is ready to be run.
 	fn ready(&self) -> bool;
 }
 
@@ -61,10 +74,14 @@ pub fn get_url_params(req: &Request) -> HashMap<String, String> {
 	hash_query
 }
 
+/// This trait is required by receptor plugins
 pub trait ReceptorPlugin {
+	/// Returns the plugin's name. Stored in the database with the message returnd
 	fn name(&self) -> &'static str;
-
+	/// This is the 'worker' function, and will be called when the ready fucntion returns true.
+	/// Currently this requires plugins to return a string.
+	/// An `Ok` will be stored, while currently an `Err` is output to the terminal on the receptor
 	fn gather(&mut self, db_conn: &Connection) -> Result<String, String>;
-
+	/// This function tells the receptor if the plugin is ready to be run.
 	fn ready(&self) -> bool;
 }