From 51ea2896cdcdf7b6027f96421a0ce2b454486e03 Mon Sep 17 00:00:00 2001
From: Santo Cariotti <santo@dcariotti.me>
Date: Wed, 4 Aug 2021 18:09:12 +0200
Subject: docs: init adds

---
 src/browser/mod.rs         |  5 +++++
 src/browser/web_browser.rs | 11 +++++++++++
 2 files changed, 16 insertions(+)

(limited to 'src/browser')

diff --git a/src/browser/mod.rs b/src/browser/mod.rs
index d5ec337..7205f27 100644
--- a/src/browser/mod.rs
+++ b/src/browser/mod.rs
@@ -6,12 +6,16 @@ use thirtyfour::prelude::WebDriverResult;
 
 mod web_browser;
 
+/// Create a new instance of `Browser` and associate it with the static variable `WEB_BROWSER`.
+/// This is an unsecure type of usage, so the block is inside the `unsafe` block
 pub async fn init(driver_url: &String) {
     unsafe {
         WEB_BROWSER = Some(Browser::new(driver_url).await);
     }
 }
 
+/// Login using the credentials from the `Config`. 'Cause its kind of nature
+/// this is an `unsafe` block, so the function is defined like that
 pub async unsafe fn login(credentials: &Config) -> WebDriverResult<()> {
     if let Some(driver) = &WEB_BROWSER {
         driver._login(credentials).await?;
@@ -20,6 +24,7 @@ pub async unsafe fn login(credentials: &Config) -> WebDriverResult<()> {
     Ok(())
 }
 
+/// Get the faculties available for booking a room
 pub async unsafe fn get_faculties() -> WebDriverResult<Option<HashMap<String, String>>> {
     if let Some(driver) = &WEB_BROWSER {
         if let Some(faculties) = driver.faculties().await? {
diff --git a/src/browser/web_browser.rs b/src/browser/web_browser.rs
index d2ba6c4..c7497cf 100644
--- a/src/browser/web_browser.rs
+++ b/src/browser/web_browser.rs
@@ -6,14 +6,19 @@ use thirtyfour::error::{WebDriverError, WebDriverErrorInfo, WebDriverErrorValue}
 use thirtyfour::prelude::{By, WebDriverResult};
 use thirtyfour::{FirefoxCapabilities, WebDriver, WebDriverCommands};
 
+/// This url is used to make the login
 const LOGIN_URL: &str = "https://studenti.smartedu.unict.it/WorkFlow2011/Logon/Logon.aspx?ReturnUrl=%2fStudenti%2fDefault.aspx";
+/// This url is used to go to the page where a student can book a room for study
 const ROOMS_URL: &str = "https://studenti.smartedu.unict.it/StudentSpaceReserv?Type=unaTantum";
 
+/// Browser struct
 pub struct Browser {
+    /// The driver for Firefox, it could be `None`
     driver: Option<WebDriver>,
 }
 
 impl Browser {
+    /// Create a new `Browser` with a Firefox driver with a personalized User-Agent
     pub async fn new(driver_url: &String) -> Self {
         let user_agent =
             "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:90.0) Gecko/20100101 Firefox/90.0";
@@ -34,6 +39,7 @@ impl Browser {
     //     Ok(())
     // }
 
+    /// Login on `LOGIN_URL`
     pub async unsafe fn _login(&self, credentials: &Config) -> WebDriverResult<()> {
         if let Some(_d) = &self.driver {
             _d.get(LOGIN_URL).await?;
@@ -57,6 +63,8 @@ impl Browser {
 
             thread::sleep(time::Duration::from_millis(2000));
 
+            // If the current url is the same as `LOGIN_URL` it means the login didn't work, so
+            // returns a "login error"
             if _d.current_url().await? == LOGIN_URL {
                 return Err(WebDriverError::SessionNotCreated(WebDriverErrorInfo {
                     status: 400,
@@ -74,6 +82,8 @@ impl Browser {
         Ok(())
     }
 
+    /// Get all faculties for booking and return an `HashMap<key, value>` when `key` is the
+    /// key for that faculty inside the `select` tag and `value` is just the text of the option.
     pub async fn faculties(&self) -> WebDriverResult<Option<HashMap<String, String>>> {
         if let Some(_d) = &self.driver {
             _d.get(ROOMS_URL).await?;
@@ -106,4 +116,5 @@ impl Browser {
     }
 }
 
+/// The static unsafe variable used to open a web browser
 pub static mut WEB_BROWSER: Option<Browser> = None;
-- 
cgit v1.2.3-18-g5258