Merge pull request #56 from studio-YOLO/add-jsdoc

Added JSDoc for all functions

src/core/black-white-filter.js

@@ -1,7 +1,13 @@
 /**
- *  Function to convert an image from color to black and white.
- *  @param {number[]} pixelArray: Image pixel array in the format [R, G, B, alpha,..., R, G, B, alpha].
- *  @returns {number[]} array of black and white image pixels.
+ * Converts an RGBA pixel array to black and white.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @returns {number[]} A black and white version of the input pixel array.
+ * 
+ * @description This function converts an RGBA pixel array to black and white by calculating 
+ * the grayscale value of each pixel and setting the RGB values to either 0 (black) or 255 (white) based on a threshold. 
+ * Finally, it returns the black and white pixel array.
+ * 
  */
 function toBlackWhite(pixelArray) {
     for (let i = 0; i < pixelArray.length; i += 4) {

src/core/change-brightness.js

@@ -1,10 +1,20 @@
 import {rgbToHsl, hslToRgb} from "../core/colorspace-conversion.js";
 
 /**
- * Function to change the brightness of an image
- * @param {number[]} pixelArray: Image pixel array in the format [R, G, B, alpha,..., R, G, B, alpha]
- * @param {number} factor: factor to adjust the brightness (-100 to 100)
- * @returns {number[]} adjustedPixelArray: Adjusted image pixel array in the format [R, G, B, alpha,..., R, G, B, alpha]
+ * Changes the brightness of an RGBA pixel array.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} factor - The brightness adjustment factor.
+ * @returns {number[]} A pixel array with adjusted brightness.
+ * 
+ * @description This function changes the brightness of an RGBA pixel array by adjusting 
+ * the lightness value in the HSL (Hue, Saturation, Lightness) color space. 
+ * The factor determines the amount of brightness adjustment applied to each pixel. 
+ * A positive factor increases brightness, making the image lighter, while a negative 
+ * factor decreases brightness, making the image darker. 
+ * A factor of 0 results in no change to the pixel array. 
+ * Finally, it returns the pixel array with adjusted brightness.
+ * 
  */
 function changeBrightness(pixelArray, factor) {
     if (factor == 0)

src/core/change-contrast.js

@@ -1,9 +1,17 @@
 /**
- *  Function that, given an array in the format [R, G, B, alpha,..., R, G, B, alpha], rescales each of its color channels along an s-curve to change the contrast
- *  @param {number[]} pixelArray: image that has to be encrypted in the format [R, G, B, alpha,..., R, G, B, alpha]
- *  @param {number} factor: scale factor for the s-curve
- *  @returns {number[]} contrastArray: an array in the format [R, G, B, alpha,..., R, G, B, alpha]
- **/
+ * Changes the contrast of an RGBA pixel array.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} factor - The contrast adjustment factor.
+ * @returns {number[]} A pixel array with adjusted contrast.
+ * 
+ * @description This function changes the contrast of an RGBA pixel array by applying a contrast adjustment factor to each color channel. 
+ * It uses a sigmoid curve function to adjust the contrast, with the given factor determining the steepness of the curve. 
+ * A factor of 0 results in no change to the pixel array. 
+ * For non-zero factors, it applies the sigmoid curve transformation to each color channel except for the alpha channel. 
+ * Finally, it returns the pixel array with adjusted contrast.
+ * 
+ */
 function changeContrast(pixelArray, factor) {
     if (factor == 0)
         return pixelArray;

src/core/change-exposure.js

@@ -1,8 +1,16 @@
 /**
- * Function to change the exposure of an image.
- * @param {number[]} pixelArray: Image pixel array in the format [R, G, B, alpha,..., R, G, B, alpha].
- * @param {number} factor: Factor to adjust the exposure (-100 to 100).
- * @returns {number[]} Pixel array of the image with adjusted exposure.
+ * Changes the exposure of an RGBA pixel array.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} factor - The exposure adjustment factor.
+ * @returns {number[]} A pixel array with adjusted exposure.
+ * 
+ * @description This function changes the exposure of an RGBA pixel array by applying an exposure adjustment factor to each RGB channel of every pixel. 
+ * The factor determines the intensity of the exposure adjustment. 
+ * A positive factor increases the brightness of the image, while a negative factor decreases the brightness. 
+ * The factor is applied to each RGB channel independently.
+ * Finally, it returns the pixel array with adjusted exposure.
+ * 
  */
 function changeExposure(pixelArray, factor) {
     for (let i = 0; i < pixelArray.length; i += 4) {

src/core/change-highlights.js

@@ -1,8 +1,15 @@
 /**
- *  Function that modifies the pixel array of an image by brightening or darkening the highlight areas by a given factor
- *  @param {number[]} pixelArray: image that has to be encoded in the format [R, G, B, alpha,..., R, G, B, alpha]
- *  @param {number[]} factor: the shadow brightening/darkening parameter that will be applied to the image
- *  @returns {number[]} outputArray: pixel array of the modified image
+ * Changes the highlights of an RGBA pixel array.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} factor - The highlights adjustment factor.
+ * @returns {number[]} A pixel array with adjusted highlights.
+ * 
+ * @description This function changes the highlights of an RGBA pixel array by adjusting the RGB values of pixels with a luminance above 128. 
+ * The factor determines the intensity of the highlights adjustment applied to those pixels. 
+ * A positive factor increases the brightness of highlights, while a negative factor decreases the brightness. 
+ * Finally, it returns the pixel array with adjusted highlights.
+ * 
  */
 function changeHighlights(pixelArray, factor) {
     for (let i = 0; i < pixelArray.length; i += 4) {

src/core/change-opacity.js

@@ -1,8 +1,14 @@
 /**
- *  Function that modifies the pixel array of an image by changing the alpha parameter with the one given as input
- *  @param {number[]} pixelArray: image that has to be encrypt in the format [R, G, B, alfa,..., R, G, B, alfa]
- *  @param {number[]} alphaValue: the alpha parameter that will be applied to the image
- *  @returns {number[]} opaquePixelArray: pixel array of the opaque image
+ * Changes the opacity (alpha value) of an RGBA pixel array.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} alphaValue - The new alpha value (opacity) to set for all pixels.
+ * @returns {number[]} A pixel array with adjusted opacity.
+ * 
+ * @description This function changes the opacity (alpha value) of an RGBA pixel array by 
+ * setting the alpha channel (transparency) to a specified value for all pixels. 
+ * Finally, it returns the pixel array with adjusted opacity.
+ * 
  */
 function changeOpacity(pixelArray, alphaValue) {
     for (let i = 0; i < pixelArray.length; i += 4) {

src/core/change-saturation.js

@@ -1,10 +1,18 @@
 import {rgbToHsl, hslToRgb} from "../core/colorspace-conversion.js";
 
 /**
- * Function to change the saturation of an image.
- * @param {number[]} pixelArray: Image pixel array in the format [R, G, B, alpha,..., R, G, B, alpha].
- * @param {number} factor: factor to adjust the saturation (-100 to 100).
- * @returns {number[]} pixel array of the saturated or desaturated image.
+ * Changes the saturation of an RGBA pixel array.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} factor - The saturation adjustment factor.
+ * @returns {number[]} A pixel array with adjusted saturation.
+ * 
+ * @description This function changes the saturation of an RGBA pixel array by adjusting the saturation value in the HSL (Hue, Saturation, Lightness) color space. 
+ * The factor determines the amount of saturation adjustment applied to each pixel. 
+ * A positive factor increases saturation, making colors more vibrant, while a negative factor decreases saturation, making colors less vibrant. 
+ * A factor of 0 results in no change to the pixel array.
+ * Finally, it returns the pixel array with adjusted saturation.
+ * 
  */
 function changeSaturation(pixelArray, factor) {
     if (factor == 0)

src/core/change-shadows.js

@@ -1,8 +1,15 @@
 /**
- *  Function that modifies the pixel array of an image by brightening or darkening the shadow areas by a given factor
- *  @param {number[]} pixelArray: image that has to be encoded in the format [R, G, B, alpha,..., R, G, B, alpha]
- *  @param {number[]} factor: the shadow brightening/darkening parameter that will be applied to the image
- *  @returns {number[]} outputArray: pixel array of the modified image
+ * Changes the shadows of an RGBA pixel array.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} factor - The shadow adjustment factor.
+ * @returns {number[]} A pixel array with adjusted shadows.
+ * 
+ * @description This function changes the shadows of an RGBA pixel array by adjusting the RGB values of pixels with a luminance below 128. 
+ * The factor determines the intensity of the shadow adjustment applied to those pixels. 
+ * A positive factor increases the darkness of shadows, while a negative factor lightens shadows.
+ * Finally, it returns the pixel array with adjusted shadows.
+ * 
  */
 function changeShadows(pixelArray, factor) {
     for (let i = 0; i < pixelArray.length; i += 4) {

src/core/change-sharpness.js

@@ -1,3 +1,19 @@
+/**
+ * Changes the sharpness of an RGBA pixel array using convolution with a sharpening kernel.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} width - The width of the image represented by the pixel array.
+ * @param {number} height - The height of the image represented by the pixel array.
+ * @param {number} factor - The sharpness adjustment factor.
+ * @returns {number[]} A pixel array with adjusted sharpness.
+ * 
+ * @description This function changes the sharpness of an RGBA pixel array by applying convolution 
+ * with a sharpening kernel. 
+ * The sharpness adjustment factor determines the intensity of the sharpening effect. 
+ * A positive factor increases sharpness, while a negative factor decreases sharpness.  
+ * Finally, it returns the pixel array with adjusted sharpness.
+ * 
+ */
 function changeSharpness(pixelArray, width, height, factor) {
     // Define a sharpening kernel
     const kernel = [

src/core/change-temperature.js

@@ -1,14 +1,15 @@
 /**
- *  Function that, given an array of pixels of an image in the format [R, G, B, alpha,..., R, G, B, alpha] adjusts 
- *  the red and blue levels to increase or decrease the temperature of the image.
+ * Changes the temperature of an RGBA pixel array.
  * 
- *  In particular:
- *  - if factor > 0: the image is heated.
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} factor - The temperature adjustment factor.
+ * @returns {number[]} A pixel array with adjusted temperature.
  * 
- *  - if factor < 0: the image is cooled.
+ * @description This function changes the temperature of an RGBA pixel array by adjusting the red and blue color channels. 
+ * A positive factor increases the "warmth" of the image by adding red and reducing blue, while a negative 
+ * factor increases the "coolness" by reducing red and adding blue. 
+ * Finally, it returns the pixel array with adjusted temperature.
  * 
- *  @param {number[]} pixelArray: image that has to be encrypt in the format [R, G, B, alpha,..., R, G, B, alpha]
- *  @returns {number[]} result: image pixel array after transformation
  */
 function changeTemperature(pixelArray, factor) {
     const clip = (value) => {

src/core/change-tint.js

@@ -1,8 +1,14 @@
 /**
- * Function to change the tint of an image.
- * @param {number[]} pixelArray: Image pixel array in the format [R, G, B, alpha,..., R, G, B, alpha].
- * @param {number} tint: Tint to apply (-100 to 100).
- * @returns {number[]} Pixel array of the image with adjusted tint.
+ * Changes the tint of an RGBA pixel array.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @param {number} tint - The tint adjustment value.
+ * @returns {number[]} A pixel array with adjusted tint.
+ * 
+ * @description This function changes the tint of an RGBA pixel array by adjusting the green channel (G) value based on the specified tint adjustment value.
+ * A higher tint value increases the green channel (making the image more green), while a lower tint value decreases the green channel (making the image less green).
+ * Finally, it returns the pixel array with adjusted tint.
+ * 
  */
 function changeTint(pixelArray, tint) {
     for (let i = 0; i < pixelArray.length; i += 4) {

src/core/colorspace-conversion.js

@@ -1,19 +1,32 @@
 /**
- * Convert RGB color values to hexadecimal representation.
- * @param {number} r - The red value (0-255).
- * @param {number} g - The green value (0-255).
- * @param {number} b - The blue value (0-255).
+ * Converts RGB color values to hexadecimal representation.
+ * 
+ * @param {number} r - The red component value (0 to 255).
+ * @param {number} g - The green component value (0 to 255).
+ * @param {number} b - The blue component value (0 to 255).
  * @returns {string} The hexadecimal representation of the RGB color.
+ * 
+ * @description This function takes the red, green, and blue component values of a color in the range 
+ * of 0 to 255 and converts them into a hexadecimal color representation. 
+ * It concatenates the components into a single hexadecimal string with the format "#RRGGBB",
+ * where RR, GG, and BB represent the hexadecimal values of the red, green, and blue components respectively. 
+ * The function returns the hexadecimal representation of the RGB color.
+ * 
  */
 function rgbToHex(r, g, b) {
     return "#" + (1 << 24 | r << 16 | g << 8 | b).toString(16).slice(1);
 }
 
 /**
- * Convert a hexadecimal color code to RGB color values.
- * @param {string} hexColor - The hexadecimal color code (e.g., "#rrggbb" or #rgb).
- * @returns {Object} An object containing the RGB color values.
+ * Converts a hexadecimal color representation to RGB color values.
+ * 
+ * @param {string} hexColor - The hexadecimal color representation (e.g., "#RRGGBB" or "#RGB").
+ * @returns {Object} An object containing the red, green, and blue component values of the RGB color.
+ * 
+ * @description This function takes a hexadecimal color representation, either in the format "#RRGGBB" or "#RGB", and converts it into its corresponding RGB color values. It first normalizes the input hexadecimal string to the format "#RRGGBB". Then, it extracts the red, green, and blue component values from the normalized string and converts them from hexadecimal to decimal. Finally, it returns an object containing the red (r), green (g), and blue (b) component values of the RGB color.
+ * 
  * @throws {Error} If the input hex color is invalid.
+ * 
  */
 function hexToRgb(hexColor) {
     hexColor = hexColor.replace(/^#?([a-f\d])([a-f\d])([a-f\d])$/i, (m, r, g, b) => r + r + g + g + b + b);
@@ -29,11 +42,15 @@ function hexToRgb(hexColor) {
 }
 
 /**
- * Convert RGB color values to HSL (Hue, Saturation, Lightness) representation.
- * @param {number} r - The red value (0-255).
- * @param {number} g - The green value (0-255).
- * @param {number} b - The blue value (0-255).
- * @returns {Object} An object containing the HSL representation of the RGB color.
+ * Converts RGB color values to HSL (Hue, Saturation, Lightness) color model.
+ * 
+ * @param {number} r - The red component value (0 to 255).
+ * @param {number} g - The green component value (0 to 255).
+ * @param {number} b - The blue component value (0 to 255).
+ * @returns {Object} An object containing the hue (h), saturation (s), and lightness (l) values in the HSL color model.
+ * 
+ * @description This function takes RGB color values and converts them into the corresponding values in the HSL (Hue, Saturation, Lightness) color model. It first normalizes the RGB values to the range 0 to 1. Then, it determines the maximum (max) and minimum (min) values among the RGB components. Based on these values, it calculates the hue (h), saturation (s), and lightness (l) components of the HSL color model. Finally, it returns an object containing these values.
+ * 
  */
 function rgbToHsl(r, g, b) {
     r /= 255;
@@ -64,11 +81,15 @@ function rgbToHsl(r, g, b) {
 }
 
 /**
- * Convert HSL (Hue, Saturation, Lightness) color values to RGB representation.
- * @param {number} h - The hue value (0-360).
- * @param {number} s - The saturation value (0-100).
- * @param {number} l - The lightness value (0-100).
- * @returns {Object} An object containing the RGB representation of the HSL color.
+ * Converts HSL (Hue, Saturation, Lightness) color values to RGB color model.
+ * 
+ * @param {number} h - The hue component value (0 to 360).
+ * @param {number} s - The saturation component value (0 to 100).
+ * @param {number} l - The lightness component value (0 to 100).
+ * @returns {Object} An object containing the red (r), green (g), and blue (b) component values in the RGB color model (0 to 255).
+ * 
+ * @description This function takes HSL color values and converts them into the corresponding values in the RGB (Red, Green, Blue) color model. It first normalizes the hue (h), saturation (s), and lightness (l) values to the range 0 to 1. Then, it calculates intermediate values based on the HSL components to derive the RGB components. Finally, it returns an object containing the red, green, and blue component values in the RGB color model.
+ * 
  */
 function hslToRgb(h, s, l) {
     s /= 100;

src/core/gray-scale-filter.js

@@ -1,7 +1,13 @@
 /**
- *  Function to convert an image to grayscale.
- *  @param {number[]} pixelArray: Image pixel array in the format [R, G, B, alpha,..., R, G, B, alpha].
- *  @returns {number[]} array of grayscale pixels of an image.
+ * Converts an RGBA pixel array to grayscale.
+ * 
+ * @param {number[]} pixelArray - An array representing pixel data in RGBA format.
+ * @returns {number[]} A grayscale version of the input pixel array.
+ * 
+ * @description This function converts an RGBA pixel array to grayscale by calculating the luminance of each 
+ * pixel and setting the RGB values to the same grayscale value.
+ * Finally, it returns the grayscale pixel array.
+ * 
  */
 function toGrayScale(pixelArray) {
     for (let i = 0; i < pixelArray.length; i += 4) {

src/core/higher-contrast.js

@@ -1,10 +1,18 @@
 /**
- * Function that given a color in the RGB format converts it to grayscale
- * and then calculates the color (black or white) with the highest contrast.
- * @param {number} r red color value
- * @param {number} g green color value
- * @param {number} b blue color value
- * @returns {object} Color with the higher contrast of the input color in the format {r: value, g:value, b:value}
+ * Determines a color with higher contrast based on the input RGB values.
+ * 
+ * @param {number} r - The red component value (0 to 255).
+ * @param {number} g - The green component value (0 to 255).
+ * @param {number} b - The blue component value (0 to 255).
+ * @returns {Object} An object containing the RGB values of the color with higher contrast.
+ * 
+ * @description This function calculates the grayscale value of the input RGB color using a weighted sum of the color components. 
+ * It then determines a color with higher contrast based on whether the grayscale value is above or below a threshold (128). 
+ * If the grayscale value is above the threshold, indicating a lighter color, the function returns an object with RGB values set 
+ * to 0, resulting in a darker color. If the grayscale value is below the threshold, indicating a darker color, the function returns 
+ * an object with RGB values set to 255, resulting in a lighter color. 
+ * The function returns an object representing the color with higher contrast.
+ * 
  */
 function higherColorContrast(r, g, b) {
     const gray = Math.round(0.299 * r + 0.587 * g + 0.114 * b)