Improving source code documentation.

src/search_results_handler/aggregation_models.rs

@@ -1,5 +1,19 @@
+//! This module provides public models for handling, storing and serializing of search results
+//! data scraped from the upstream search engines.
+
 use serde::Serialize;
 
+/// A named struct to store and serialize the individual search result from all the scraped
+/// and aggregated search results from the upstream search engines.
+///
+/// # Fields
+///
+/// * `title` - The title of the search result.
+/// * `visiting_url` - The url which is accessed when clicked on it (href url in html in simple
+/// words).
+/// * `url` - The url to be displayed below the search result title in html.
+/// * `description` - The description of the search result.
+/// * `engine` - The names of the upstream engines from which this results were provided.
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SearchResult {
@@ -11,6 +25,16 @@ pub struct SearchResult {
 }
 
 impl SearchResult {
+    /// Constructs a new `SearchResult` with the given arguments needed for the struct.
+    ///
+    /// # Arguments
+    ///
+    /// * `title` - The title of the search result.
+    /// * `visiting_url` - The url which is accessed when clicked on it
+    /// (href url in html in simple words).
+    /// * `url` - The url to be displayed below the search result title in html.
+    /// * `description` - The description of the search result.
+    /// * `engine` - The names of the upstream engines from which this results were provided.
     pub fn new(
         title: String,
         visiting_url: String,
@@ -28,6 +52,17 @@ impl SearchResult {
     }
 }
 
+/// A named struct to store the raw scraped search results scraped search results from the
+/// upstream search engines before aggregating it.It derives the Clone trait which is needed
+/// to write idiomatic rust using `Iterators`.
+///
+/// # Fields
+///
+/// * `title` - The title of the search result.
+/// * `visiting_url` - The url which is accessed when clicked on it
+/// (href url in html in simple words).
+/// * `description` - The description of the search result.
+/// * `engine` - The names of the upstream engines from which this results were provided.
 #[derive(Clone)]
 pub struct RawSearchResult {
     pub title: String,
@@ -37,6 +72,15 @@ pub struct RawSearchResult {
 }
 
 impl RawSearchResult {
+    /// Constructs a new `RawSearchResult` with the given arguments needed for the struct.
+    ///
+    /// # Arguments
+    ///
+    /// * `title` - The title of the search result.
+    /// * `visiting_url` - The url which is accessed when clicked on it
+    /// (href url in html in simple words).
+    /// * `description` - The description of the search result.
+    /// * `engine` - The names of the upstream engines from which this results were provided.
     pub fn new(
         title: String,
         visiting_url: String,
@@ -50,6 +94,12 @@ impl RawSearchResult {
             engine,
         }
     }
+
+    /// A function which adds the engine name provided as a string into a vector of strings.
+    ///
+    /// # Arguments
+    ///
+    /// * `engine` - Takes an engine name provided as a String.
     pub fn add_engines(&mut self, engine: String) {
         self.engine.push(engine)
     }
@@ -59,6 +109,14 @@ impl RawSearchResult {
     }
 }
 
+/// A named struct to store and serialize the all the search results scraped and aggregated
+/// from the upstream search engines.
+///
+/// # Fields
+///
+/// * `results` - Stores the individual serializable `SearchResult` struct into a vector of
+/// `SearchResult` structs.
+/// * `page_query` - Stores the current pages search query `q` provided in the search url.
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SearchResults {
@@ -67,6 +125,14 @@ pub struct SearchResults {
 }
 
 impl SearchResults {
+    /// Constructs a new `SearchResult` with the given arguments needed for the struct.
+    ///
+    /// # Arguments
+    ///
+    /// * `results` - Takes an argument of individual serializable `SearchResult` struct
+    /// and stores it into a vector of `SearchResult` structs.
+    /// * `page_query` - Takes an argument of current page`s search query `q` provided in
+    /// the search url.
     pub fn new(results: Vec<SearchResult>, page_query: String) -> Self {
         SearchResults {
             results,

src/search_results_handler/aggregator.rs

@@ -1,3 +1,6 @@
+//! This module provides the functionality to scrape and gathers all the results from the upstream
+//! search engines and then removes duplicate results.
+
 use std::collections::HashMap;
 
 use super::{
@@ -7,17 +10,28 @@ use super::{
 
 use crate::engines::{duckduckgo, searx};
 
-// A function that aggregates all the scraped results from the above upstream engines and
-// then removes duplicate results and if two results are found to be from two or more engines
-// then puts their names together to show the results are fetched from these upstream engines
-// and then removes all data from the HashMap and puts into a struct of all results aggregated
-// into a vector and also adds the query used into the struct this is neccessory because otherwise
-// the search bar in search remains empty if searched from the query url
-//
-// For Example:
-//
-// If you search from the url like *https://127.0.0.1/search?q=huston* then the search bar should
-// contain the word huston and not remain empty.
+/// A function that aggregates all the scraped results from the above upstream engines and
+/// then removes duplicate results and if two results are found to be from two or more engines
+/// then puts their names together to show the results are fetched from these upstream engines
+/// and then removes all data from the HashMap and puts into a struct of all results aggregated
+/// into a vector and also adds the query used into the struct this is neccessory because 
+/// otherwise the search bar in search remains empty if searched from the query url
+///
+/// # Example:
+///
+/// If you search from the url like `https://127.0.0.1/search?q=huston` then the search bar should
+/// contain the word huston and not remain empty.
+/// 
+/// # Arguments
+///
+/// * `query` - Accepts a string to query with the above upstream search engines.
+/// * `page` - Accepts an Option<u32> which could either be a None or a valid page number.
+///
+/// # Error
+///
+/// Returns an error a reqwest and scraping selector errors if any error occurs in the results 
+/// function in either `searx` or `duckduckgo` or both otherwise returns a `SearchResults struct`
+/// containing appropriate values.
 pub async fn aggregate(
     query: &str,
     page: Option<u32>,

src/search_results_handler/user_agent.rs

@@ -1,6 +1,12 @@
+//! This module provides the functionality to generate random user agent string.
+
 use fake_useragent::{Browsers, UserAgentsBuilder};
 
-// A function to generate random user agent to improve privacy of the user.
+/// A function to generate random user agent to improve privacy of the user.
+///
+/// # Returns
+///
+/// A randomly generated user agent string.
 pub fn random_user_agent() -> String {
     UserAgentsBuilder::new()
         .cache(false)