Improving source code documentation.

src/bin/websurfx.rs

@@ -1,3 +1,8 @@
+//! Main module of the application
+//!
+//! This module contains the main function which handles the logging of the application to the
+//! stdout and handles the command line arguments provided and launches the `websurfx` server.
+
 use std::ops::RangeInclusive;
 
 use websurfx::server::routes;
@@ -8,6 +13,7 @@ use clap::{command, Parser};
 use env_logger::Env;
 use handlebars::Handlebars;
 
+/// A commandline arguments struct.
 #[derive(Parser, Debug, Default)]
 #[clap(author = "neon_arch", version, about = "Websurfx server application")]
 #[command(propagate_version = true)]
@@ -19,8 +25,18 @@ struct CliArgs {
 
 const PORT_RANGE: RangeInclusive<usize> = 1024..=65535;
 
-// A function to check whether port is valid u32 number or is in range
-// between [1024-65536] otherwise display an appropriate error message.
+/// A function to check whether port is valid u32 number or is in range
+/// between [1024-65536] otherwise display an appropriate error message.
+///
+/// # Arguments
+///
+/// * `s` - Takes a commandline argument port as a string.
+///
+/// # Error
+///
+/// Check whether the provided argument to `--port` commandline option is a valid
+/// u16 argument and returns it as a u16 value otherwise returns an error with an
+/// appropriate error message.
 fn is_port_in_range(s: &str) -> Result<u16, String> {
     let port: usize = s
         .parse()
@@ -36,7 +52,12 @@ fn is_port_in_range(s: &str) -> Result<u16, String> {
     }
 }
 
-// The function that launches the main server and handle routing functionality
+/// The function that launches the main server and registers all the routes of the website.
+///
+/// # Error
+///
+/// Returns an error if the port is being used by something else on the system and is not
+/// available for being used for other applications.
 #[actix_web::main]
 async fn main() -> std::io::Result<()> {
     let args = CliArgs::parse();
@@ -68,7 +89,7 @@ async fn main() -> std::io::Result<()> {
             .service(routes::settings) // settings page
             .default_service(web::route().to(routes::not_found)) // error page
     })
-    // Start server on 127.0.0.1:8080
+    // Start server on 127.0.0.1 with the user provided port number. for example 127.0.0.1:8080.
     .bind(("127.0.0.1", args.port))?
     .run()
     .await