From 5d2ac60a79a578e236b6459509266d61645a3550 Mon Sep 17 00:00:00 2001 From: James ABIB <61329786+jabibamman@users.noreply.github.com> Date: Tue, 14 Nov 2023 11:41:10 +0100 Subject: [PATCH] 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 --------- Co-authored-by: restyled-io[bot] <32688539+restyled-io[bot]@users.noreply.github.com> Co-authored-by: Restyled.io --- README.md | 14 ++++++++++++++ client/src/image.rs | 16 ++++++++++++++++ client/src/julia.rs | 11 +++++++++++ complex/src/complex_operations.rs | 18 ++++++++++++++++++ complex/src/julia_descriptor_impl.rs | 10 ++++++++++ shared/src/types/complex.rs | 5 +++++ shared/src/types/filesystem.rs | 13 +++++++++++++ shared/src/types/fractal_descriptor.rs | 24 ++++++++++++++++++++++-- shared/src/types/messages.rs | 20 ++++++++++++++++++++ shared/src/types/pixel_data.rs | 5 +++++ shared/src/types/pixel_intensity.rs | 7 +++++++ shared/src/types/point.rs | 5 +++++ shared/src/types/range.rs | 5 +++++ shared/src/types/resolution.rs | 5 +++++ shared/src/types/u8data.rs | 5 +++++ shared/src/utils/filesystem.rs | 20 ++++++++++++++++++++ 16 files changed, 181 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fe9ff39..9e6a383 100644 --- a/README.md +++ b/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. diff --git a/client/src/image.rs b/client/src/image.rs index 750cf74..c5cce00 100644 --- a/client/src/image.rs +++ b/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; diff --git a/client/src/julia.rs b/client/src/julia.rs index 2efbea6..1bcfcda 100644 --- a/client/src/julia.rs +++ b/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, Vec> { let descriptor = &fragment_task.fractal.fractal_type; let descriptor = match descriptor { diff --git a/complex/src/complex_operations.rs b/complex/src/complex_operations.rs index cfb6d64..19e3ca4 100644 --- a/complex/src/complex_operations.rs +++ b/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); diff --git a/complex/src/julia_descriptor_impl.rs b/complex/src/julia_descriptor_impl.rs index 7f54cd1..9f42094 100644 --- a/complex/src/julia_descriptor_impl.rs +++ b/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; } diff --git a/shared/src/types/complex.rs b/shared/src/types/complex.rs index eb5af30..7110049 100644 --- a/shared/src/types/complex.rs +++ b/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, diff --git a/shared/src/types/filesystem.rs b/shared/src/types/filesystem.rs index 2fd138a..738498c 100644 --- a/shared/src/types/filesystem.rs +++ b/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, diff --git a/shared/src/types/fractal_descriptor.rs b/shared/src/types/fractal_descriptor.rs index 5d9ff48..9104a3e 100644 --- a/shared/src/types/fractal_descriptor.rs +++ b/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, diff --git a/shared/src/types/messages.rs b/shared/src/types/messages.rs index b9b3770..ac7c8d2 100644 --- a/shared/src/types/messages.rs +++ b/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, diff --git a/shared/src/types/pixel_data.rs b/shared/src/types/pixel_data.rs index 97a46a2..de9ca69 100644 --- a/shared/src/types/pixel_data.rs +++ b/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, diff --git a/shared/src/types/pixel_intensity.rs b/shared/src/types/pixel_intensity.rs index 3cb22ca..c59e549 100644 --- a/shared/src/types/pixel_intensity.rs +++ b/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, diff --git a/shared/src/types/point.rs b/shared/src/types/point.rs index 6f3397c..83c8de3 100644 --- a/shared/src/types/point.rs +++ b/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, diff --git a/shared/src/types/range.rs b/shared/src/types/range.rs index ec111f1..590317d 100644 --- a/shared/src/types/range.rs +++ b/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, diff --git a/shared/src/types/resolution.rs b/shared/src/types/resolution.rs index a299bf9..e2f0373 100644 --- a/shared/src/types/resolution.rs +++ b/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, diff --git a/shared/src/types/u8data.rs b/shared/src/types/u8data.rs index df03c47..f6ce07f 100644 --- a/shared/src/types/u8data.rs +++ b/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, diff --git a/shared/src/utils/filesystem.rs b/shared/src/utils/filesystem.rs index 09dc6e6..2d4539f 100644 --- a/shared/src/utils/filesystem.rs +++ b/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 { 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 { 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,6 +42,9 @@ 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::(), extension); @@ -37,11 +52,16 @@ pub fn get_file_path(filename: &str, path: PathBuf, extension: &str) -> String { 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;