💡 chore: add documentation to the code (#302)

src/templates/mod.rs

@@ -1,4 +1,5 @@
-//!
+//! This module provides other modules to handle both the view and its partials for the `websurfx`
+//! search engine frontend.
 
 mod partials;
 pub mod views;

src/templates/partials/bar.rs

@@ -1,8 +1,17 @@
-//!
+//! A module that handles `bar` partial for the `search_bar` partial and the home/index/main page in the `websurfx` frontend.
 
-use maud::{html, Markup,PreEscaped};
+use maud::{html, Markup, PreEscaped};
 
+/// A functions that handles the html code for the bar for the `search_bar` partial and the
+/// home/index/main page in the search engine frontend.
 ///
+/// # Arguments
+///
+/// * `query` - It takes the current search query provided by user as an argument.
+///
+/// # Returns
+///
+/// It returns the compiled html code for the search bar as a result.
 pub fn bar(query: &str) -> Markup {
     html!(
         (PreEscaped("<div class=\"search_bar\">"))

src/templates/partials/footer.rs

@@ -1,8 +1,13 @@
-//!
+//! A module that handles the footer for all the pages in the `websurfx` frontend.
 
 use maud::{html, Markup, PreEscaped};
 
+/// A functions that handles the html code for the footer for all the pages in the search engine
+/// frontend.
 ///
+/// # Returns
+///
+/// It returns the compiled html code for the footer as a result.
 pub fn footer() -> Markup {
     html!(
         footer{

src/templates/partials/header.rs

@@ -1,9 +1,18 @@
-//!
+//! A module that handles the header for all the pages in the `websurfx` frontend.
 
 use crate::templates::partials::navbar::navbar;
 use maud::{html, Markup, PreEscaped, DOCTYPE};
 
+/// A function that handles the html code for the header for all the pages in the search engine frontend.
 ///
+/// # Arguments
+///
+/// * `colorscheme` - It takes the colorscheme name as an argument.
+/// * `theme` - It takes the theme name as an argument.
+///
+/// # Returns
+///
+/// It returns the compiled html markup code for the header as a result.
 pub fn header(colorscheme: &str, theme: &str) -> Markup {
     html!(
         (DOCTYPE)

src/templates/partials/mod.rs

@@ -1,8 +1,8 @@
-//!
+//! This module provides other modules to handle the partials for the views in the `websurfx` frontend.
 
+pub mod bar;
 pub mod footer;
 pub mod header;
 pub mod navbar;
-pub mod bar;
-pub mod settings_tabs;
 pub mod search_bar;
+pub mod settings_tabs;

src/templates/partials/navbar.rs

@@ -1,8 +1,12 @@
-//!
+//! A module that handles `navbar` partial for the header partial in the `websurfx` frontend.
 
 use maud::{html, Markup};
 
+/// A functions that handles the html code for the header partial.
 ///
+/// # Returns
+///
+/// It returns the compiled html code for the navbar as a result.
 pub fn navbar() -> Markup {
     html!(
         nav{

src/templates/partials/search_bar.rs

@@ -1,12 +1,24 @@
-//!
+//! A module that handles `search bar` partial for the search page in the `websurfx` frontend.
 
 use maud::{html, Markup, PreEscaped};
 
 use crate::{models::aggregation_models::EngineErrorInfo, templates::partials::bar::bar};
 
+/// A constant holding the named safe search level options for the corresponding values 0, 1 and 2.
 const SAFE_SEARCH_LEVELS_NAME: [&str; 3] = ["None", "Low", "Moderate"];
 
+/// A functions that handles the html code for the search bar for the search page.
 ///
+/// # Arguments
+///
+/// * `engine_errors_info` - It takes the engine errors list containing errors for each upstream
+/// search engine which failed to provide results as an argument.
+/// * `safe_search_level` - It takes the safe search level with values from 0-2 as an argument.
+/// * `query` - It takes the current search query provided by user as an argument.
+///
+/// # Returns
+///
+/// It returns the compiled html code for the search bar as a result.
 pub fn search_bar(
     engine_errors_info: &[EngineErrorInfo],
     safe_search_level: u8,

src/templates/partials/settings_tabs/cookies.rs

@@ -1,8 +1,12 @@
-//!
+//! A module that handles the engines tab for setting page view in the `websurfx` frontend.
 
 use maud::{html, Markup};
 
+/// A functions that handles the html code for the cookies tab for the settings page for the search page.
 ///
+/// # Returns
+///
+/// It returns the compiled html markup code for the cookies tab.
 pub fn cookies() -> Markup {
     html!(
         div class="cookies tab"{

src/templates/partials/settings_tabs/engines.rs

@@ -1,8 +1,16 @@
-//!
+//! A module that handles the engines tab for setting page view in the `websurfx` frontend.
 
 use maud::{html, Markup};
 
+/// A functions that handles the html code for the engines tab for the settings page for the search page.
 ///
+/// # Arguments
+///
+/// * `engine_names` - It takes the list of all available engine names as an argument.
+///
+/// # Returns
+///
+/// It returns the compiled html markup code for the engines tab.
 pub fn engines(engine_names: &[&String]) -> Markup {
     html!(
         div class="engines tab"{

src/templates/partials/settings_tabs/general.rs

@@ -1,10 +1,15 @@
-//!
+//! A module that handles the general tab for setting page view in the `websurfx` frontend.
 
 use maud::{html, Markup};
 
-const SAFE_SEARCH_LEVELS: [(u8, &'static str); 3] = [(0, "None"), (1, "Low"), (2, "Moderate")];
+/// A constant holding the named safe search level options for the corresponding values 0, 1 and 2.
+const SAFE_SEARCH_LEVELS: [(u8, &str); 3] = [(0, "None"), (1, "Low"), (2, "Moderate")];
 
+/// A functions that handles the html code for the general tab for the settings page for the search page.
 ///
+/// # Returns
+///
+/// It returns the compiled html markup code for the general tab.
 pub fn general() -> Markup {
     html!(
         div class="general tab active"{

src/templates/partials/settings_tabs/mod.rs

@@ -1,6 +1,7 @@
-//!
+//! This module provides other modules to handle the partials for the tabs for the settings page
+//! view in the `websurfx` frontend.
 
-pub mod general;
-pub mod engines;
 pub mod cookies;
+pub mod engines;
+pub mod general;
 pub mod user_interface;

src/templates/partials/settings_tabs/user_interface.rs

@@ -1,9 +1,21 @@
-//!
+//! A module that handles the user interface tab for setting page view in the `websurfx` frontend.
 
 use crate::handler::paths::{file_path, FileType};
 use maud::{html, Markup};
 use std::fs::read_dir;
 
+/// A helper function that helps in building the list of all available colorscheme/theme names
+/// present in the colorschemes and themes folder respectively.
+///
+/// # Arguments
+///
+/// * `style_type` - It takes the style type of the values `theme` and `colorscheme` as an
+/// argument.
+///
+/// # Error
+///
+/// Returns a list of colorscheme/theme names as a vector of tuple strings on success otherwise
+/// returns a standard error message.
 fn style_option_list(
     style_type: &str,
 ) -> Result<Vec<(String, String)>, Box<dyn std::error::Error + '_>> {
@@ -14,13 +26,18 @@ fn style_option_list(
         style_type,
     ))? {
         let style_name = file?.file_name().to_str().unwrap().replace(".css", "");
-        style_option_names.push((style_name.clone(), style_name.replace("-", " ")));
+        style_option_names.push((style_name.clone(), style_name.replace('-', " ")));
     }
 
     Ok(style_option_names)
 }
 
+/// A functions that handles the html code for the user interface tab for the settings page for the search page.
+///
+/// # Error
 ///
+/// It returns the compiled html markup code for the user interface tab on success otherwise
+/// returns a standard error message.
 pub fn user_interface() -> Result<Markup, Box<dyn std::error::Error>> {
     Ok(html!(
         div class="user_interface tab"{

src/templates/views/about.rs

@@ -1,10 +1,19 @@
-//!
+//! A module that handles the view for the about page in the `websurfx` frontend.
 
 use maud::{html, Markup};
 
 use crate::templates::partials::{footer::footer, header::header};
 
+/// A function that handles the html code for the about page view in the search engine frontend.
 ///
+/// # Arguments
+///
+/// * `colorscheme` - It takes the colorscheme name as an argument.
+/// * `theme` - It takes the theme name as an argument.
+///
+/// # Returns
+///
+/// It returns the compiled html markup code as a result.
 pub fn about(colorscheme: &str, theme: &str) -> Markup {
     html!(
         (header(colorscheme, theme))

src/templates/views/index.rs

@@ -1,16 +1,25 @@
-//!
+//! A module that handles the view for the index/home/main page in the `websurfx` frontend.
 
 use maud::{html, Markup, PreEscaped};
 
 use crate::templates::partials::{bar::bar, footer::footer, header::header};
 
+/// A function that handles the html code for the index/html/main page view in the search engine frontend.
 ///
-pub fn index(colorscheme: &str, theme: &str, query: &str) -> Markup {
+/// # Arguments
+///
+/// * `colorscheme` - It takes the colorscheme name as an argument.
+/// * `theme` - It takes the theme name as an argument.
+///
+/// # Returns
+///
+/// It returns the compiled html markup code as a result.
+pub fn index(colorscheme: &str, theme: &str) -> Markup {
     html!(
         (header(colorscheme, theme))
         main class="search-container"{
             img src="../images/websurfx_logo.png" alt="Websurfx meta-search engine logo";
-            (bar(query))
+            (bar(&String::default()))
             (PreEscaped("</div>"))
         }
         script src="static/index.js"{}

src/templates/views/mod.rs

@@ -1,7 +1,8 @@
-//!
+//! This module provides other modules to handle view for each individual page in the
+//! `websurfx` frontend.
 
 pub mod about;
 pub mod index;
 pub mod not_found;
-pub mod settings;
 pub mod search;
+pub mod settings;

src/templates/views/not_found.rs

@@ -1,15 +1,24 @@
-//!
+//! A module that handles the view for the 404 page in the `websurfx` frontend.
 
 use crate::templates::partials::{footer::footer, header::header};
 use maud::{html, Markup};
 
+/// A function that handles the html code for the 404 page view in the search engine frontend.
 ///
+/// # Arguments
+///
+/// * `colorscheme` - It takes the colorscheme name as an argument.
+/// * `theme` - It takes the theme name as an argument.
+///
+/// # Returns
+///
+/// It returns the compiled html markup code as a result.
 pub fn not_found(colorscheme: &str, theme: &str) -> Markup {
     html!(
         (header(colorscheme, theme))
         main class="error_container"{
          img src="images/robot-404.svg" alt="Image of broken robot.";
-         div class="error_content"{
+         .error_content{
           h1{"Aw! snap"}
           h2{"404 Page Not Found!"}
           p{"Go to "{a href="/"{"search page"}}}

src/templates/views/search.rs

@@ -1,4 +1,4 @@
-//!
+//! A module that handles the view for the search page in the `websurfx` frontend.
 
 use maud::{html, Markup, PreEscaped};
 
@@ -7,7 +7,18 @@ use crate::{
     templates::partials::{footer::footer, header::header, search_bar::search_bar},
 };
 
+/// A function that handles the html code for the search page view in the search engine frontend.
 ///
+/// # Arguments
+///
+/// * `colorscheme` - It takes the colorscheme name as an argument.
+/// * `theme` - It takes the theme name as an argument.
+/// * `query` - It takes the current search query provided by the user as an argument.
+/// * `search_results` - It takes the aggregated search results as an argument.
+///
+/// # Returns
+///
+/// It returns the compiled html markup code as a result.
 pub fn search(
     colorscheme: &str,
     theme: &str,

src/templates/views/settings.rs

@@ -1,4 +1,4 @@
-//!
+//! A module that handles the view for the settings page in the `websurfx` frontend.
 
 use maud::{html, Markup};
 
@@ -10,7 +10,18 @@ use crate::templates::partials::{
     },
 };
 
+/// A function that handles the html code for the settings page view in the search engine frontend.
 ///
+/// # Arguments
+///
+/// * `colorscheme` - It takes the colorscheme name as an argument.
+/// * `theme` - It takes the theme name as an argument.
+/// * `engine_names` - It takes a list of engine names as an argument.
+///
+/// # Error
+///
+/// This function returns a compiled html markup code on success otherwise returns a standard error
+/// message.
 pub fn settings(
     colorscheme: &str,
     theme: &str,