Improving source code documentation.

src/server/routes.rs

@@ -1,3 +1,7 @@
+//! This module provides the functionality to handle different routes of the `websurfx`
+//! meta search engine website and provide approriate response to each route/page
+//! when requested.
+
 use std::fs::read_to_string;
 
 use crate::search_results_handler::aggregator::aggregate;
@@ -5,12 +9,21 @@ use actix_web::{get, web, HttpRequest, HttpResponse};
 use handlebars::Handlebars;
 use serde::Deserialize;
 
+/// A named struct which deserializes all the user provided search parameters and stores them.
+///
+/// # Fields
+///
+/// * `q` - It stores the search parameter option `q` (or query in simple words)
+/// of the search url.
+/// * `page` - It stores the search parameter `page` (or pageno in simple words)
+/// of the search url.
 #[derive(Debug, Deserialize)]
 struct SearchParams {
     q: Option<String>,
     page: Option<u32>,
 }
 
+/// Handles the route of index page or main page of the `websurfx` meta search engine website.
 #[get("/")]
 pub async fn index(
     hbs: web::Data<Handlebars<'_>>,
@@ -19,6 +32,8 @@ pub async fn index(
     Ok(HttpResponse::Ok().body(page_content))
 }
 
+/// Handles the route of any other accessed route/page which is not provided by the
+/// website essentially the 404 error page.
 pub async fn not_found(
     hbs: web::Data<Handlebars<'_>>,
 ) -> Result<HttpResponse, Box<dyn std::error::Error>> {
@@ -29,6 +44,20 @@ pub async fn not_found(
         .body(page_content))
 }
 
+/// Handles the route of search page of the `websurfx` meta search engine website and it takes
+/// two search url parameters `q` and `page` where `page` parameter is optional.
+///
+/// # Example
+///
+/// ```bash
+/// curl "http://127.0.0.1:8080/search?q=sweden&page=1"
+/// ```
+/// 
+/// Or
+///
+/// ```bash
+/// curl "http://127.0.0.1:8080/search?q=sweden"
+/// ```
 #[get("/search")]
 pub async fn search(
     hbs: web::Data<Handlebars<'_>>,
@@ -54,6 +83,7 @@ pub async fn search(
     }
 }
 
+/// Handles the route of robots.txt page of the `websurfx` meta search engine website.
 #[get("/robots.txt")]
 pub async fn robots_data(_req: HttpRequest) -> Result<HttpResponse, Box<dyn std::error::Error>> {
     let page_content: String = read_to_string("./public/robots.txt")?;
@@ -62,6 +92,7 @@ pub async fn robots_data(_req: HttpRequest) -> Result<HttpResponse, Box<dyn std:
         .body(page_content))
 }
 
+/// Handles the route of about page of the `websurfx` meta search engine website.
 #[get("/about")]
 pub async fn about(
     hbs: web::Data<Handlebars<'_>>,
@@ -70,6 +101,7 @@ pub async fn about(
     Ok(HttpResponse::Ok().body(page_content))
 }
 
+/// Handles the route of settings page of the `websurfx` meta search engine website.
 #[get("/settings")]
 pub async fn settings(
     hbs: web::Data<Handlebars<'_>>,
@@ -77,3 +109,6 @@ pub async fn settings(
     let page_content: String = hbs.render("settings", &"")?;
     Ok(HttpResponse::Ok().body(page_content))
 }
+
+// TODO: Write tests for tesing parameters for search function that if provided with something
+// other than u32 like alphabets and special characters than it should panic