From bcf8fba4f0fad07a7a1cc0a66d359dc8038b5c7f Mon Sep 17 00:00:00 2001 From: Brendan Golden Date: Sat, 23 Nov 2024 18:26:28 +0000 Subject: [PATCH] doc: added proper docs --- src/lib.rs | 136 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 106 insertions(+), 30 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 5f9424c..2705941 100644 --- a/src/lib.rs +++ b/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 { success: i8, @@ -14,39 +14,56 @@ struct WolvesResultSingle { 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, - member_id: String, - first_name: String, - last_name: String, - contact_email: String, - opt_in_email: String, - student_id: Option, - note: Option, - expiry: String, - requested: String, - approved: String, - sitename: String, - domain: String, + /// Club/Soc the user is a member of + pub committee: String, + /// ID which uniquely identifies them on teh site + pub member_id: String, + /// First Name + pub first_name: String, + /// Last Name + pub last_name: String, + /// Email that they have set in their profile: + /// + /// Note: This does not indicate if they wish to be contacted via this address. + pub contact_email: 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, + /// Optional note set by Committee + pub note: Option, + /// 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, - name: String, - // Link to their page such as https://ulwolves.ie/society/computer - link: String, - // array of Committee members member_id's - committee: Vec, + /// ID of teh club/Society + pub id: String, + /// Name of the Club/Society + pub name: String, + /// Link to their page such as + pub link: String, + /// Array of Committee members ``member_id````'s + pub committee: Vec, } #[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(&self, wolves_endpoint: &str, api_key: &str) -> Vec { 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 - // uses the api key for each club/soc + /// Get the members of a Club?Society based on teh API key inputted + /// + /// # 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 = client.get_members("api_key_club_1"); + /// ``` pub async fn get_members(&self, api_key: &str) -> Vec { self.get_bulk::("get_members", api_key).await } - // command to get club/soc and committee members - // uses the instance key if it exists + /// Get information about teh Club/Soc, including committee members + /// + /// # 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 = 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 = client.get_committees(); + /// ``` pub async fn get_committees(&self) -> Vec { if let Some(api_key) = &self.base_key { self.get_bulk::("get_cns", api_key).await @@ -110,8 +168,26 @@ impl Client { } } - // method to get member_id from an email - // email can be either the login email or contact email + /// Get the ``member_id`` for a specific email if it exists. + /// + /// # 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 = 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 = client.get_member("example@example.ie"); + /// ``` pub async fn get_member(self, email: &str) -> Option { // if the key isnt set then we cant do anything. let api_key = match &self.base_key {