Doc - RustDoc implemention (#26)

* doc(rustdoc): add filesystem documentation

This commit adds several utility functions for file system operations. The functions include retrieving the current working directory, obtaining the workspace directory, getting a directory path as a `PathBuf`, mapping a `FileExtension` enum variant to its corresponding file extension string, generating a file path with a random component in the filename, and checking if a given path represents an existing directory. Additionally, this commit includes tests for each utility function to ensure their correct functionality.

doc: Provides functions for file system operations, focusing on directories and file extensions.
Includes utilities for working with the current working directory,
workspace directory, and checking if a directory exists.

- Added `get_current_working_dir()` function to retrieve the current working directory
- Added `get_workspace_dir()` function to obtain the workspace directory
- Added `get_dir_path_buf()` function to retrieve the directory path as a `PathBuf`
- Added `get_extension_str()` function to map a `FileExtension` enum variant to its corresponding file extension string
- Added `get_file_path()` function to generate a file path with a random component in the filename
- Added `dir_exists()` function to check if a given path represents an existing directory

Tests:
- Included tests for each utility function

* doc(rustdoc): add filesystem documentation

This commit adds several utility functions for file system operations. The functions include retrieving the current working directory, obtaining the workspace directory, getting a directory path as a `PathBuf`, mapping a `FileExtension` enum variant to its corresponding file extension string, generating a file path with a random component in the filename, and checking if a given path represents an existing directory. Additionally, this commit includes tests for each utility function to ensure their correct functionality.

doc: Provides functions for file system operations, focusing on directories and file extensions.
Includes utilities for working with the current working directory,
workspace directory, and checking if a directory exists.

- Added `get_current_working_dir()` function to retrieve the current working directory
- Added `get_workspace_dir()` function to obtain the workspace directory
- Added `get_dir_path_buf()` function to retrieve the directory path as a `PathBuf`
- Added `get_extension_str()` function to map a `FileExtension` enum variant to its corresponding file extension string
- Added `get_file_path()` function to generate a file path with a random component in the filename
- Added `dir_exists()` function to check if a given path represents an existing directory

Tests:
- Included tests for each utility function

* doc(readme): Add documentation generation instructions

Added instructions on how to generate documentation for all packages without including dependencies and with dependencies. This will help contributors easily generate and access the documentation.

* doc(types): add rustdoc to all frakt types

* doc(client): add rustdoc to client fun

* doc(complex): add rustdoc to complex fun

* Restyled by rustfmt (#27)

Co-authored-by: Restyled.io <commits@restyled.io>

---------

Co-authored-by: restyled-io[bot] <32688539+restyled-io[bot]@users.noreply.github.com>
Co-authored-by: Restyled.io <commits@restyled.io>

README.md

@@ -81,6 +81,20 @@ To build and the complex library (used by other components):
 cargo build -p complex
 ```
 
+## Documentation
+
+To generate documentation for all packages without including dependencies (recommended):
+
+```bash
+cargo doc --no-deps --open
+```
+
+To generate documentation for all packages including dependencies:
+
+```bash
+cargo doc --open
+```
+
 ## Contributing
 
 Contributions are welcome. Please follow standard contribution guidelines for pull requests.

client/src/image.rs

@@ -2,6 +2,22 @@ use std::process::Command;
 
 use shared::utils::filesystem::dir_exists;
 
+/// Opens an image file with the default image viewer of the system.
+///
+/// This function checks if the provided path exists and then opens the image file
+/// using the appropriate command based on the operating system.
+///
+/// # Arguments
+/// * `path` - A string slice that holds the path to the image file.
+///
+/// # OS Specific Behavior
+/// - Windows: Uses `cmd /c start` to open the image.
+/// - Linux: Uses `xdg-open` to open the image.
+/// - macOS: Uses `open` to open the image.
+/// - Other OS: Prints "OS not supported" message.
+///
+/// # Panics
+/// Panics if the command to open the image cannot be spawned.
 pub fn open_image(path: &str) -> () {
     if !dir_exists(path) {
         return;

client/src/julia.rs

@@ -5,6 +5,17 @@ use shared::types::complex::Complex;
 use shared::types::fractal_descriptor::FractalType::Julia;
 use shared::types::messages::FragmentTask;
 
+/// Generates an image of the Julia set fractal based on the provided fragment task.
+///
+/// # Arguments
+/// * `fragment_task`: A `FragmentTask` containing details such as the fractal type, resolution, and range.
+///
+/// # Returns
+/// Returns an `ImageBuffer` containing the generated Julia set fractal.
+///
+/// # Details
+/// This function scales the coordinates based on the provided resolution and range, computes the number of
+/// iterations for each pixel, and then maps these iterations to a color value.
 pub fn generate_julia_set(fragment_task: FragmentTask) -> ImageBuffer<Rgb<u8>, Vec<u8>> {
     let descriptor = &fragment_task.fractal.fractal_type;
     let descriptor = match descriptor {

complex/src/complex_operations.rs

@@ -1,12 +1,26 @@
 use shared::types::complex::Complex;
 
+/// Provides a set of operations for complex number arithmetic.
 pub trait ComplexOperations {
+    /// Constructs a new complex number.
     fn new(re: f64, im: f64) -> Self;
+
+    /// Adds two complex numbers and returns the result.
     fn add(&self, other: &Self) -> Self;
+
+    /// Subtracts another complex number from this one and returns the result.
     fn sub(&self, other: &Self) -> Self;
+
+    /// Multiplies two complex numbers and returns the result.
     fn mul(&self, other: &Self) -> Self;
+
+    /// Squares the complex number and returns the result.
     fn square(&self) -> Self;
+
+    /// Returns the squared magnitude of the complex number.
     fn magnitude_squared(&self) -> f64;
+
+    /// Returns the Euclidean norm (magnitude) of the complex number.
     fn norm(&self) -> f64;
 }
 
@@ -47,6 +61,10 @@ impl ComplexOperations for Complex {
 mod complex_tests {
     use super::*;
 
+    // Series of tests for each operation, verifying the correctness
+    // of complex number arithmetic such as addition, subtraction,
+    // multiplication, squaring, and calculation of magnitude and norm.
+
     #[test]
     fn test_add() {
         let a = Complex::new(-2.0, 5.0);

complex/src/julia_descriptor_impl.rs

@@ -3,11 +3,21 @@ use shared::types::complex::Complex;
 use shared::types::fractal_descriptor::JuliaDescriptor;
 use shared::types::resolution::Resolution;
 
+/// Provides operations specific to the Julia fractal.
 pub trait JuliaOperations {
+    /// Constructs a new `JuliaDescriptor` with the specified complex number and divergence threshold.
     fn new(c: Complex, divergence_threshold_square: f64) -> Self;
+
+    /// Converts pixel coordinates to a complex number based on the resolution.
     fn to_complex(&self, x: u16, y: u16, resolution: &Resolution) -> Complex;
+
+    /// Iterates over a complex point and returns the number of iterations before it diverges.
     fn iterate_complex_point(&self, complex_point: &Complex, max_iteration: u16) -> u16;
+
+    /// Returns the square of the divergence threshold.
     fn divergence_threshold_square(&self) -> f64;
+
+    /// Returns a reference to the complex number `c` used in the Julia fractal formula.
     fn c(&self) -> &Complex;
 }
 

shared/src/types/complex.rs

@@ -1,3 +1,8 @@
+/// A `Complex` number with real (`re`) and imaginary (`im`) parts.
+///
+/// # Attributes
+/// * `re` - The real part of the complex number, represented as a `f64`.
+/// * `im` - The imaginary part of the complex number, also a `f64`.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Complex {
     pub re: f64,

shared/src/types/filesystem.rs

@@ -1,13 +1,26 @@
+/// Represents the types of directories used in the application.
+///
+/// `Current` - Refers to the current working directory.
+/// `Workspace` - Designates the workspace directory, often used in development environments.
 pub enum DirType {
     Current,
     Workspace,
 }
 
+/// Specifies the types of files or entities in a file system.
+///
+/// `File` - Represents a standard file.
+/// `Directory` - Represents a directory.
 pub enum FileType {
     File,
     Directory,
 }
 
+/// Enumerates the supported image file extensions.
+///
+/// `PNG` - Portable Network Graphics format, used for images with transparency.
+/// `JPG` - JPEG compression format, commonly used for digital photography.
+/// `JPEG` - A variant of the JPG extension, often used interchangeably.
 pub enum FileExtension {
     PNG,
     JPG,

shared/src/types/fractal_descriptor.rs

@@ -1,24 +1,44 @@
 use crate::types::complex::Complex;
 
+/// Represents the type of fractal to be generated.
+///
+/// Variants:
+/// - `Julia(JuliaDescriptor)`: Represents a Julia fractal with its specific descriptor.
+/// - `Mandelbrot(MandelbrotDescriptor)`: Represents a Mandelbrot fractal (currently commented out).
+/// - `...`: Placeholder for additional fractal types.
 #[derive(Debug, Clone, PartialEq)]
 pub enum FractalType {
     Julia(JuliaDescriptor),
-    //Mandelbrot(MandelbrotDescriptor),
-    //...
+    // Mandelbrot(MandelbrotDescriptor),
+    // ...
 }
 
+/// Describes parameters specific to a Julia fractal.
+///
+/// Attributes:
+/// - `c`: A `Complex` number representing the constant parameter of the Julia set.
+/// - `divergence_threshold_square`: The square of the divergence threshold. Points whose magnitude square exceeds this threshold are considered to diverge.
 #[derive(Debug, Clone, PartialEq)]
 pub struct JuliaDescriptor {
     pub c: Complex,
     pub divergence_threshold_square: f64,
 }
 
+/// Describes parameters specific to a Mandelbrot fractal.
+///
+/// Attributes:
+/// - `divergence_threshold_square`: The square of the divergence threshold. Points whose magnitude square exceeds this threshold are considered to diverge.
+/// - `max_iteration`: Maximum number of iterations to determine whether a point diverges.
 #[derive(Debug, Clone, PartialEq)]
 pub struct MandelbrotDescriptor {
     pub divergence_threshold_square: f64,
     pub max_iteration: u16,
 }
 
+/// General descriptor for a fractal, encompassing different fractal types.
+///
+/// Attributes:
+/// - `fractal_type`: A variant of `FractalType` specifying the type of fractal and its parameters.
 #[derive(Debug, Clone, PartialEq)]
 pub struct FractalDescriptor {
     pub fractal_type: FractalType,

shared/src/types/messages.rs

@@ -4,12 +4,25 @@ use crate::types::range::Range;
 use crate::types::resolution::Resolution;
 use crate::types::u8data::U8Data;
 
+/// Represents a request for a fragment of work from a worker.
+///
+/// Attributes:
+/// - `worker_name`: A `String` representing the name of the worker making the request.
+/// - `maximal_work_load`: An `u32` indicating the maximum workload (in terms of pixels) the worker can handle.
 #[derive(Debug, Clone, PartialEq)]
 pub struct FragmentRequest {
     worker_name: String,
     maximal_work_load: u32,
 }
 
+/// Describes a task assigned to a worker for fractal computation by a Server.
+///
+/// Attributes:
+/// - `id`: An `U8Data` structure, typically representing an identifier for the task.
+/// - `fractal`: A `FractalDescriptor` detailing the type and parameters of the fractal to be computed.
+/// - `max_iteration`: A `u16` specifying the maximum number of iterations for the fractal computation.
+/// - `resolution`: A `Resolution` specifying the resolution of the fragment to be computed.
+/// - `range`: A `Range` defining the physical space coordinates for the fragment.
 #[derive(Debug, Clone, PartialEq)]
 pub struct FragmentTask {
     pub id: U8Data,
@@ -19,6 +32,13 @@ pub struct FragmentTask {
     pub range: Range,
 }
 
+/// Represents the result of a fragment computation by a worker.
+///
+/// Attributes:
+/// - `id`: An `U8Data` structure, typically representing the identifier of the task for which this is the result.
+/// - `resolution`: A `Resolution` specifying the resolution of the computed fragment.
+/// - `range`: A `Range` defining the physical space coordinates for the computed fragment.
+/// - `pixels`: A `PixelData` containing the computed pixel data for the fragment.
 #[derive(Debug, Clone, PartialEq)]
 pub struct FragmentResult {
     id: U8Data,

shared/src/types/pixel_data.rs

@@ -1,3 +1,8 @@
+/// Represents data associated with a set of pixels in an image or a fragment of an image.
+///
+/// Attributes:
+/// - `offset`: A `u32` indicating the starting point or offset in a larger array or buffer where the pixel data begins.
+/// - `count`: A `u32` representing the number of pixels (or data points) that are included starting from the `offset`.
 #[derive(Debug, Clone, PartialEq)]
 pub struct PixelData {
     pub offset: u32,

shared/src/types/pixel_intensity.rs

@@ -1,3 +1,10 @@
+/// Represents the intensity of a pixel in fractal rendering, particularly in the context of iterations.
+///
+/// Attributes:
+/// - `zn`: A `f32` representing the magnitude at the end of the iteration process.
+///   This is typically used to determine the color or intensity of a pixel in fractal images.
+/// - `count`: A `f32` reflecting the number of iterations performed, normalized by the maximum number of iterations.
+///   This value is often used to apply color gradients based on the iteration depth.
 #[derive(Debug, Clone, PartialEq)]
 pub struct PixelIntensity {
     pub zn: f32,

shared/src/types/point.rs

@@ -1,3 +1,8 @@
+/// Represents a point in a two-dimensional space.
+///
+/// Attributes:
+/// - `x`: A `f64` representing the x-coordinate of the point.
+/// - `y`: A `f64` representing the y-coordinate of the point.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Point {
     pub x: f64,

shared/src/types/range.rs

@@ -1,5 +1,10 @@
 use crate::types::point::Point;
 
+/// Defines a rectangular range in a two-dimensional space, represented by minimum and maximum points.
+///
+/// Attributes:
+/// - `min`: A `Point` defining the minimum (bottom-left) corner of the range.
+/// - `max`: A `Point` defining the maximum (top-right) corner of the range.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Range {
     pub min: Point,

shared/src/types/resolution.rs

@@ -1,3 +1,8 @@
+/// Represents the resolution of an image or a grid, defined by the number of pixels or cells along the x and y axes.
+///
+/// Attributes:
+/// - `nx`: A `u16` representing the number of pixels or cells along the x-axis (width).
+/// - `ny`: A `u16` representing the number of pixels or cells along the y-axis (height).
 #[derive(Debug, Clone, PartialEq)]
 pub struct Resolution {
     pub nx: u16,

shared/src/types/u8data.rs

@@ -1,3 +1,8 @@
+/// Represents a segment of data, typically used for handling parts of a byte stream.
+///
+/// Attributes:
+/// - `offset`: A `u32` indicating the starting position in a byte stream or array.
+/// - `count`: A `u32` denoting the length or the number of elements in the segment starting from `offset`.
 #[derive(Debug, Clone, PartialEq)]
 pub struct U8Data {
     pub offset: u32,

shared/src/utils/filesystem.rs

@@ -1,17 +1,27 @@
+/// Provides functions for file system operations, focusing on directories and file extensions.
+/// Includes utilities for working with the current working directory, workspace directory,
+/// and checking if a directory exists.
 use std::{env, path::PathBuf};
 
 use crate::types::filesystem::FileExtension;
 
 use rand::random;
 
+/// Returns the current working directory as a `PathBuf`.
+/// Propagates any errors encountered.
 fn get_current_working_dir() -> std::io::Result<PathBuf> {
     env::current_dir()
 }
 
+/// Obtains the workspace directory. Typically the current working directory.
+/// Errors are propagated from `get_current_working_dir`.
 pub fn get_workspace_dir() -> std::io::Result<PathBuf> {
     Ok(get_current_working_dir()?)
 }
 
+/// Retrieves the directory path as a `PathBuf`. In release mode, returns the current working directory.
+/// In debug mode, appends `target` to the workspace directory path.
+/// Panics if the directory cannot be obtained.
 pub fn get_dir_path_buf() -> PathBuf {
     if cfg!(not(debug_assertions)) {
         get_current_working_dir().expect("Failed to get the current directory")
@@ -22,6 +32,8 @@ pub fn get_dir_path_buf() -> PathBuf {
     }
 }
 
+/// Maps a `FileExtension` enum variant to its corresponding file extension string.
+/// Returns `png`, `jpg`, or `jpeg`.
 pub fn get_extension_str(extension: FileExtension) -> &'static str {
     match extension {
         FileExtension::PNG => "png",
@@ -30,18 +42,26 @@ pub fn get_extension_str(extension: FileExtension) -> &'static str {
     }
 }
 
+/// Generates a file path string with a random component in the filename.
+/// Constructs the path from the given filename, path, and extension.
+/// Ensures unique filenames.
 pub fn get_file_path(filename: &str, path: PathBuf, extension: &str) -> String {
     let mut path_buf = path;
     let file_name_with_extension = format!("{}-{}.{}", filename, random::<u32>(), extension);
     path_buf.push(file_name_with_extension);
     path_buf.to_str().unwrap_or_default().to_string()
 }
 
+/// Checks if a given path string represents an existing directory.
+/// Returns `true` if the path exists and is a directory, `false` otherwise.
 pub fn dir_exists(path: &str) -> bool {
     let path_buf = PathBuf::from(path);
     path_buf.exists() && path_buf.is_dir()
 }
 
+/// The module includes tests for each utility function, ensuring their correct functionality.
+/// These tests cover scenarios like checking if a directory exists, getting directory strings in different modes,
+///  and validating file extension strings.
 #[cfg(test)]
 mod tests {
     use super::dir_exists;