Better documentation

README.md

@@ -3,7 +3,7 @@
 Libcaesium is a simple library performing JPEG, PNG, WebP and GIF (experimental) compression/optimization written in
 Rust, with a C interface.
 
-> [!CAUTION]
+> [!WARNING]
 > starting from v0.6.0 the library is written in Rust and no longer in C. There's a C interface, but it's not backward
 > compatible with the <0.6.0.
 

src/lib.rs

@@ -26,6 +26,17 @@ mod webp;
 mod convert;
 pub mod parameters;
 
+/// Compresses an image file from the input path and writes the compressed image to the output path.
+///
+/// # Arguments
+///
+/// * `input_path` - A string representing the path to the input image file.
+/// * `output_path` - A string representing the path to the output compressed image file.
+/// * `parameters` - A reference to `CSParameters` containing compression settings.
+///
+/// # Returns
+///
+/// * `Result<(), CaesiumError>` - Returns `Ok(())` if compression is successful, otherwise returns a `CaesiumError`.
 pub fn compress(
     input_path: String,
     output_path: String,
@@ -66,6 +77,16 @@ pub fn compress(
     Ok(())
 }
 
+/// Compresses an image file in memory and returns the compressed image as a byte vector.
+///
+/// # Arguments
+///
+/// * `in_file` - A vector of bytes representing the input image file.
+/// * `parameters` - A reference to `CSParameters` containing compression settings.
+///
+/// # Returns
+///
+/// * `Result<Vec<u8>, CaesiumError>` - Returns a vector of bytes representing the compressed image if successful, otherwise returns a `CaesiumError`.
 pub fn compress_in_memory(
     in_file: Vec<u8>,
     parameters: &CSParameters,
@@ -91,6 +112,19 @@ pub fn compress_in_memory(
     Ok(compressed_file)
 }
 
+/// Compresses an image file in memory up to a specified size and returns the compressed image as a byte vector.
+///
+/// # Arguments
+///
+/// * `in_file` - A vector of bytes representing the input image file.
+/// * `parameters` - A mutable reference to `CSParameters` containing compression settings.
+/// * `max_output_size` - The maximum size of the output compressed image in bytes.
+/// * `return_smallest` - A boolean indicating whether to return the smallest compressed image if the desired size is not achieved.
+///
+/// # Returns
+///
+/// * `Result<Vec<u8>, CaesiumError>` - Returns a vector of bytes representing the compressed image if successful, otherwise returns a `CaesiumError`.
+
 pub fn compress_to_size_in_memory(
     in_file: Vec<u8>,
     parameters: &mut CSParameters,
@@ -202,6 +236,19 @@ pub fn compress_to_size_in_memory(
     Ok(compressed_file)
 }
 
+/// Compresses an image file from the input path up to a specified size and writes the compressed image to the output path.
+///
+/// # Arguments
+///
+/// * `input_path` - A string representing the path to the input image file.
+/// * `output_path` - A string representing the path to the output compressed image file.
+/// * `parameters` - A mutable reference to `CSParameters` containing compression settings.
+/// * `max_output_size` - The maximum size of the output compressed image in bytes.
+/// * `return_smallest` - A boolean indicating whether to return the smallest compressed image if the desired size is not achieved.
+///
+/// # Returns
+///
+/// * `Result<(), CaesiumError>` - Returns `Ok(())` if compression is successful, otherwise returns a `CaesiumError`.
 pub fn compress_to_size(
     input_path: String,
     output_path: String,
@@ -237,6 +284,19 @@ pub fn compress_to_size(
     Ok(())
 }
 
+/// Converts an image file from the input path to a specified format and writes the converted image to the output path.
+///
+/// # Arguments
+///
+/// * `input_path` - A string representing the path to the input image file.
+/// * `output_path` - A string representing the path to the output converted image file.
+/// * `parameters` - A reference to `CSParameters` containing conversion settings.
+/// * `format` - The target format to convert the image to.
+///
+/// # Returns
+///
+/// * `Result<(), CaesiumError>` - Returns `Ok(())` if conversion is successful, otherwise returns a `CaesiumError`.
+
 pub fn convert(input_path: String, output_path: String, parameters: &CSParameters, format: SupportedFileTypes) -> error::Result<()> {
 
     let file_type = get_filetype_from_path(&input_path);
@@ -269,6 +329,18 @@ pub fn convert(input_path: String, output_path: String, parameters: &CSParameter
 
     Ok(())
 }
+
+/// Converts an image file in memory to a specified format and returns the converted image as a byte vector.
+///
+/// # Arguments
+///
+/// * `in_file` - A vector of bytes representing the input image file.
+/// * `parameters` - A reference to `CSParameters` containing conversion settings.
+/// * `format` - The target format to convert the image to.
+///
+/// # Returns
+///
+/// * `Result<Vec<u8>, CaesiumError>` - Returns a vector of bytes representing the converted image if successful, otherwise returns a `CaesiumError`.
 pub fn convert_in_memory(in_file: Vec<u8>, parameters: &CSParameters, format: SupportedFileTypes) -> Result<Vec<u8>, CaesiumError> {
     convert::convert_in_memory(in_file, format, parameters)
 }

src/parameters.rs

@@ -1,5 +1,12 @@
 use crate::parameters::TiffCompression::Deflate;
 
+/// Enum representing different chroma subsampling options for JPEG compression.
+/// 
+/// - `CS444`: 4:4:4 chroma subsampling
+/// - `CS422`: 4:2:2 chroma subsampling
+/// - `CS420`: 4:2:0 chroma subsampling
+/// - `CS411`: 4:1:1 chroma subsampling
+/// - `Auto`: Automatic chroma subsampling
 #[derive(Copy, Clone, PartialEq)]
 pub enum ChromaSubsampling {
     CS444,
@@ -9,6 +16,12 @@ pub enum ChromaSubsampling {
     Auto,
 }
 
+/// Enum representing different compression algorithms for TIFF images.
+/// 
+/// - `Uncompressed`: No compression
+/// - `Lzw`: LZW compression
+/// - `Deflate`: Deflate compression
+/// - `Packbits`: PackBits compression
 #[derive(Copy, Clone, PartialEq)]
 pub enum TiffCompression {
     Uncompressed = 0,
@@ -17,19 +30,37 @@ pub enum TiffCompression {
     Packbits = 3,
 }
 
+/// Enum representing different deflate levels for TIFF compression.
+/// 
+/// - `Fast`: Fast compression
+/// - `Balanced`: Balanced compression
+/// - `Best`: Best compression
 #[derive(Copy, Clone, PartialEq)]
 pub enum TiffDeflateLevel {
     Fast = 1,
     Balanced = 6,
     Best = 9,
 }
+
+/// Struct representing parameters for JPEG compression.
+/// 
+/// Fields:
+/// - `quality`: Quality of the JPEG image (0-100)
+/// - `chroma_subsampling`: Chroma subsampling option
+/// - `progressive`: Whether to use progressive JPEG
 #[derive(Copy, Clone)]
 pub struct JpegParameters {
     pub quality: u32,
     pub chroma_subsampling: ChromaSubsampling,
-    pub progressive: bool
+    pub progressive: bool,
 }
 
+/// Struct representing parameters for PNG compression.
+/// 
+/// Fields:
+/// - `quality`: Quality of the PNG image (0-100)
+/// - `force_zopfli`: Whether to force the use of Zopfli compression (can be very slow)
+/// - `optimization_level`: Optimization level for PNG compression (0-6)
 #[derive(Copy, Clone)]
 pub struct PngParameters {
     pub quality: u32,
@@ -37,22 +68,48 @@ pub struct PngParameters {
     pub optimization_level: u8,
 }
 
+/// Struct representing parameters for GIF compression.
+/// 
+/// Fields:
+/// - `quality`: Quality of the GIF image (0-100)
 #[derive(Copy, Clone)]
 pub struct GifParameters {
     pub quality: u32,
 }
 
+/// Struct representing parameters for WebP compression.
+/// 
+/// Fields:
+/// - `quality`: Quality of the WebP image (0-100)
 #[derive(Copy, Clone)]
 pub struct WebPParameters {
     pub quality: u32,
 }
 
+/// Struct representing parameters for TIFF compression.
+/// 
+/// Fields:
+/// - `algorithm`: Compression algorithm for TIFF
+/// - `deflate_level`: Deflate level for TIFF compression
 #[derive(Copy, Clone)]
 pub struct TiffParameters {
     pub algorithm: TiffCompression,
     pub deflate_level: TiffDeflateLevel,
 }
 
+/// Struct representing overall compression parameters.
+/// 
+/// Fields:
+/// - `jpeg`: JPEG compression parameters
+/// - `png`: PNG compression parameters
+/// - `gif`: GIF compression parameters
+/// - `webp`: WebP compression parameters
+/// - `tiff`: TIFF compression parameters
+/// - `keep_metadata`: Whether to keep metadata in the compressed image
+/// - `optimize`: Whether to use lossless compression
+/// - `width`: Width of the output image
+/// - `height`: Height of the output image
+/// - `output_size`: Desired output size of the compressed image
 #[derive(Copy, Clone)]
 pub struct CSParameters {
     pub jpeg: JpegParameters,