Document web module (#1041)

Author: Luni-4

rust-code-analysis-web/Cargo.toml

@@ -8,9 +8,6 @@ keywords = ["metrics"]
 description = "Run a web service to compute and export code metrics"
 license = "MPL-2.0"
 
-[[bin]]
-name = "rust-code-analysis-web"
-
 [dependencies]
 actix-rt = "^2.6"
 actix-web = "^4.2"

rust-code-analysis-web/src/main.rs renamed to rust-code-analysis-web/src/bin/rust-code-analysis-web.rs

@@ -1,15 +1,8 @@
-// After adding new fields for min and max in the json (server.rs line 630) this error arose:
-// error: recursion limit reached while expanding `json_internal!`
-// This solution was proposed as help by the compiler
-// for the full error details check here :https://github.com/mozilla/rust-code-analysis/pull/793#discussion_r817610530
-#![recursion_limit = "256"]
-mod web;
-
 use std::thread::available_parallelism;
 
 use clap::Parser;
 
-use web::server;
+use rust_code_analysis_web::server::run;
 
 #[derive(Parser, Debug)]
 #[clap(
@@ -40,7 +33,7 @@ async fn main() {
             .get()
     });
 
-    if let Err(e) = server::run(&opts.host, opts.port, num_jobs).await {
+    if let Err(e) = run(&opts.host, opts.port, num_jobs).await {
         eprintln!(
             "Cannot run the server at {}:{}: {}",
             opts.host, opts.port, e

rust-code-analysis-web/src/lib.rs

@@ -0,0 +1,7 @@
+// After adding new fields for min and max in the json (server.rs line 630) this error arose:
+// error: recursion limit reached while expanding `json_internal!`
+// This solution was proposed as help by the compiler
+// for the full error details check here :https://github.com/mozilla/rust-code-analysis/pull/793#discussion_r817610530
+#![recursion_limit = "256"]
+pub mod web;
+pub use web::*;

rust-code-analysis-web/src/web/comment.rs

@@ -2,28 +2,42 @@ use serde::{Deserialize, Serialize};
 
 use rust_code_analysis::{rm_comments, Callback, ParserTrait};
 
+/// Payload containing source code with comments to be removed.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct WebCommentPayload {
+    /// Payload identifier.
     pub id: String,
+    /// Source code filename.
     pub file_name: String,
+    /// Source code with comments to be removed.
     pub code: String,
 }
 
+/// Server response containing the source code without comments.
 #[derive(Debug, Serialize)]
 pub struct WebCommentResponse {
+    /// Server response identifier.
     pub id: String,
+    /// Source code without comments.
+    ///
+    /// If `None`, an error occurred processing the request.
     pub code: Option<Vec<u8>>,
 }
 
+/// Source code information.
 #[derive(Debug, Deserialize)]
 pub struct WebCommentInfo {
+    /// Source code filename.
     pub file_name: String,
 }
 
+/// Server request configuration.
 pub struct WebCommentCfg {
+    /// Request identifier.
     pub id: String,
 }
 
+/// Unit structure to implement the `Callback` trait.
 pub struct WebCommentCallback;
 
 impl Callback for WebCommentCallback {

rust-code-analysis-web/src/web/function.rs

@@ -3,28 +3,40 @@ use serde_json::{self, Value};
 
 use rust_code_analysis::{function, Callback, FunctionSpan, ParserTrait};
 
+/// Payload containing source code with function spans to be retrieved.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct WebFunctionPayload {
+    /// Payload identifier.
     pub id: String,
+    /// Source code filename.
     pub file_name: String,
+    /// Source code with function spans to be retrieved.
     pub code: String,
 }
 
+/// Server response containing function spans for the requested source code.
 #[derive(Debug, Serialize)]
 pub struct WebFunctionResponse {
+    /// Server response identifier.
     pub id: String,
+    /// Function spans for the requested source code.
     pub spans: Vec<FunctionSpan>,
 }
 
+/// Source code information.
 #[derive(Debug, Deserialize)]
 pub struct WebFunctionInfo {
+    /// Source code filename.
     pub file_name: String,
 }
 
+/// Server request configuration.
 pub struct WebFunctionCfg {
+    /// Request identifier.
     pub id: String,
 }
 
+/// Unit structure to implement the `Callback` trait.
 pub struct WebFunctionCallback;
 
 impl Callback for WebFunctionCallback {

rust-code-analysis-web/src/web/metrics.rs

@@ -4,34 +4,58 @@ use std::path::PathBuf;
 
 use rust_code_analysis::{metrics, Callback, FuncSpace, ParserTrait};
 
+/// Payload containing source code used to compute metrics.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct WebMetricsPayload {
+    /// Payload identifier.
     pub id: String,
+    /// Source code filename.
     pub file_name: String,
+    /// Source code used to compute metrics.
     pub code: String,
+    /// Flag to consider only unit space metrics.
     pub unit: bool,
 }
 
+/// Server response containing metrics for every space present in
+/// the requested source code.
 #[derive(Debug, Serialize)]
 pub struct WebMetricsResponse {
+    /// Server response identifier.
     pub id: String,
+    /// Source code programming language.
     pub language: String,
+    /// Metrics for every space contained in the requested source code.
+    ///
+    /// If `None`, an error occurred processing the request.
     pub spaces: Option<FuncSpace>,
 }
 
+/// Source code information.
 #[derive(Debug, Deserialize)]
 pub struct WebMetricsInfo {
+    /// Source code filename.
     pub file_name: String,
+    /// Unit space code.
+    ///
+    ///
+    /// If `None`, the entire code is considered.
     pub unit: Option<String>,
 }
 
+/// Server request configuration.
 pub struct WebMetricsCfg {
+    /// Request identifier.
     pub id: String,
+    /// Path to the source file.
     pub path: PathBuf,
+    /// Flag to consider only unit space metrics.
     pub unit: bool,
+    /// Source code programming language.
     pub language: String,
 }
 
+/// Unit structure to implement the `Callback` trait.
 pub struct WebMetricsCallback;
 
 impl Callback for WebMetricsCallback {

rust-code-analysis-web/src/web/server.rs

@@ -218,6 +218,30 @@ async fn ping() -> HttpResponse {
     HttpResponse::Ok().body(())
 }
 
+/// Runs an HTTP Server which provides a series of services.
+///
+/// Each service corresponds to a functionality of the main library and can be
+/// accessed through a different route.
+///
+/// # Examples
+///
+/// ```no_run
+/// use rust_code_analysis_web::server::run;
+///
+/// #[actix_web::main]
+/// async fn main() {
+///     let host = "127.0.0.1";
+///     let port = 8080;
+///     let num_threads = 4;
+///
+///     // Runs a server on a determined host with a specific port and using a
+///     // certain number of threads.
+///     // If the server does not run correctly, an error will be shown.
+///     if let Err(e) = run(host, port, num_threads).await {
+///        eprintln!("Cannot run the server at {host}:{port}: {e}");
+///     }
+/// }
+/// ```
 pub async fn run(host: &str, port: u16, n_threads: usize) -> std::io::Result<()> {
     let max_size = 1024 * 1024 * 4;