doc: added proper docs

src/lib.rs

@@ -1,7 +1,7 @@
 use serde::{Deserialize, Serialize};
 
 // This is what Wolves returns to us
-// success will always be 1/
+// success will always be 1?
 #[derive(Deserialize, Serialize, Debug)]
 struct WolvesResult<T> {
   success: i8,
@@ -14,39 +14,56 @@ struct WolvesResultSingle<T> {
   result: T,
 }
 
-// get_members
+/// Data returned for a member of a club/soc
 #[derive(Deserialize, Serialize, Debug)]
 pub struct WolvesUser {
   // TODO: Might be worth trying to get this replaced with the club/soc ID?
-  committee: String,
+  /// Club/Soc the user is a member of
-  member_id: String,
+  pub committee: String,
-  first_name: String,
+  /// ID which uniquely identifies them on teh site
-  last_name: String,
+  pub member_id: String,
-  contact_email: String,
+  /// First Name
-  opt_in_email: String,
+  pub first_name: String,
-  student_id: Option<String>,
+  /// Last Name
-  note: Option<String>,
+  pub last_name: String,
-  expiry: String,
+  /// Email that they have set in their profile: <https://ulwolves.ie/memberships/profile>
-  requested: String,
+  ///
-  approved: String,
+  /// Note: This does not indicate if they wish to be contacted via this address.
-  sitename: String,
+  pub contact_email: String,
-  domain: String,
+  /// Denotes if a user has opted into being emailed: ``0`` or ``1``
+  pub opt_in_email: String,
+  /// if the member is/was a student this is their ID
+  pub student_id: Option<String>,
+  /// Optional note set by Committee
+  pub note: Option<String>,
+  /// When their membership will expire: ``yyyy-MM-dd HH:mm:ss``
+  pub expiry: String,
+  /// When member requested membership: ``yyyy-MM-dd HH:mm:ss``
+  pub requested: String,
+  /// When the member was approved: ``yyyy-MM-dd HH:mm:ss``
+  pub approved: String,
+  /// Name of the site the user is a member of:``UL Wolves``
+  pub sitename: String,
+  /// Domain of the site they are a member of: ``ulwolves.ie``
+  pub domain: String,
 }
 
-// get_cns
+/// Information on an individual club/soc
 #[derive(Deserialize, Serialize, Debug)]
 pub struct WolvesCNS {
-  id: String,
+  /// ID of teh club/Society
-  name: String,
+  pub id: String,
-  // Link to their page such as https://ulwolves.ie/society/computer
+  /// Name of the Club/Society
-  link: String,
+  pub name: String,
-  // array of Committee members member_id's
+  /// Link to their page such as <https://ulwolves.ie/society/computer>
-  committee: Vec<String>,
+  pub link: String,
+  /// Array of Committee members ``member_id````'s
+  pub committee: Vec<String>,
 }
 
 #[derive(Serialize, Deserialize, Debug)]
 #[serde(untagged)]
-pub enum WolvesUserExists {
+enum WolvesUserExists {
   B(bool),
   S(String),
 }
@@ -57,6 +74,22 @@ pub struct Client {
 }
 
 impl Client {
+  /// Create a new client for teh Wolves API
+  ///
+  /// # Arguments
+  /// * `base_wolves` - Base URL for the requests, for example: ``https://cp.ulwolves.ie/api``
+  /// * `base_key` - An instance API Key for running higher level privilege tasks
+  ///
+  /// # Examples
+  ///
+  /// ```rust
+  /// use wolves_oxidised::Client;
+  /// let client = Client::new("https://cp.ulwolves.ie/api", None);
+  /// ```
+  /// ```rust
+  /// use wolves_oxidised::Client;
+  /// let client = Client::new("https://cp.ulwolves.ie/api", Some("api_key"));
+  /// ```
   pub fn new(base_wolves: &str, base_key: Option<&str>) -> Self {
     Self {
       base_wolves: base_wolves.to_string(),
@@ -64,7 +97,7 @@ impl Client {
     }
   }
 
-  // This should handle any method where wolves returns an array
+  /// General method to get endpoints which return an array
   async fn get_bulk<T: serde::de::DeserializeOwned>(&self, wolves_endpoint: &str, api_key: &str) -> Vec<T> {
     if self.base_wolves.is_empty() {
       return vec![];
@@ -94,14 +127,39 @@ impl Client {
     vec![]
   }
 
-  // this is the command that gets a list of all members in a club/soc
+  /// Get the members of a Club?Society based on teh API key inputted
-  // uses the api key for each club/soc
+  ///
+  /// # Arguments
+  /// * `api_key` - API key scoped to teh specific club/soc
+  ///
+  /// # Examples
+  ///
+  /// ```rust
+  /// use wolves_oxidised::{Client, WolvesUser};
+  /// let client = Client::new("https://cp.ulwolves.ie/api", None);
+  /// let result: Vec<WolvesUser> = client.get_members("api_key_club_1");
+  /// ```
   pub async fn get_members(&self, api_key: &str) -> Vec<WolvesUser> {
     self.get_bulk::<WolvesUser>("get_members", api_key).await
   }
 
-  // command to get club/soc and committee members
+  /// Get information about teh Club/Soc, including committee members
-  // uses the instance key if it exists
+  ///
+  /// # Examples
+  /// No instance API key set
+  /// ```rust
+  /// use wolves_oxidised::{Client, WolvesCNS};
+  /// let client = Client::new("https://cp.ulwolves.ie/api", None);
+  /// let result: Vec<WolvesCNS> = client.get_committees();
+  /// assert_eq!(result.len(), 0);
+  /// ```
+  ///
+  /// Instance API key set, will return details if there are no other errors
+  /// ```rust
+  /// use wolves_oxidised::{Client, WolvesCNS};
+  /// let client = Client::new("https://cp.ulwolves.ie/api", Some("api_key_instance"));
+  /// let result: Vec<WolvesCNS> = client.get_committees();
+  /// ```
   pub async fn get_committees(&self) -> Vec<WolvesCNS> {
     if let Some(api_key) = &self.base_key {
       self.get_bulk::<WolvesCNS>("get_cns", api_key).await
@@ -110,8 +168,26 @@ impl Client {
     }
   }
 
-  // method to get member_id from an email
+  /// Get the ``member_id`` for a specific email if it exists.
-  // email can be either the login email or contact email
+  ///
+  /// # Arguments
+  /// * `api_key` - API key scoped to teh specific club/soc
+  ///
+  /// # Examples
+  /// No instance API key set
+  /// ```rust
+  /// use wolves_oxidised::Client;
+  /// let client = Client::new("https://cp.ulwolves.ie/api", None);
+  /// let result: Option<i64> = client.get_member("example@example.ie");
+  /// assert!(result.is_none());
+  /// ```
+  ///
+  /// Instance API key set, will return details if there are no other errors
+  /// ```rust
+  /// use wolves_oxidised::Client;
+  /// let client = Client::new("https://cp.ulwolves.ie/api", Some("api_key_instance"));
+  /// let result: Option<i64> = client.get_member("example@example.ie");
+  /// ```
   pub async fn get_member(self, email: &str) -> Option<i64> {
     // if the key isnt set then we cant do anything.
     let api_key = match &self.base_key {