update documentation (#14)

integraal/src/lib.rs

@@ -3,10 +3,14 @@
 //! *Integraal* aims to provide generic and efficient tools for [numerical integration][NI] in
 //! the Rust Programming Language.
 //!
-//! The crate currently implements a very specific subsection of its ambitious scope. It roughly
-//! corresponds to the example provided for the [`Integraal`] example.
+//! # Quickstart
+//!
+//! Multiple standalone examples are provided in the GitHub [repository][GH]. You can also look at
+//! the example provided for the [`Integraal`] structure for a very concise overview of the crate's
+//! usage.
 //!
 //! [NI]: https://en.wikipedia.org/wiki/Numerical_integration
+//! [GH]: https://github.com/imrn99/integraal
 
 // --- CUSTOM LINTS
 

integraal/src/parameters.rs

@@ -7,8 +7,8 @@ use crate::Scalar;
 /// This is essentially a discretization of the integrated space.
 ///
 /// Currently, the supported integration domain can only be one-dimensionnal, described using
-/// `f64` values (i.e. the type used for further computations). In the future, adding support
-/// for higher dimension & generic value type can be considered.
+/// a value type (implementing [`Scalar`]). In the future, adding support for higher dimension
+/// can be considered.
 #[derive(Debug, Clone)]
 pub enum DomainDescriptor<'a, T: Scalar> {
     /// List of values taken by the variable on which we integrate.

integraal/src/structure/definitions.rs

@@ -18,7 +18,9 @@ pub enum IntegraalError {
 /// Main integral computation structure
 ///
 /// This structure is used as the entrypoint for integral definition and computation. It follows
-/// a pseudo-builder patterns where the function description is reset after a computation.
+/// a pseudo-builder patterns where the function description is reset after a computation. This is
+/// the preferred behavior as many different integrals may be computed over the same domain in
+/// scientific problems.
 ///
 /// # Usage
 ///
@@ -29,7 +31,7 @@ pub enum IntegraalError {
 /// - a [`DomainDescriptor`] instance, used to describe the space over which the integral span
 /// - a [`FunctionDescriptor`] instance, used to describe the integrated function
 /// - a [`ComputeMethod`] instance, used to choose which numerical integration method will be used
-///   for computation
+///   for value approximation
 ///
 /// In the future, another object might be included to control the execution backend.
 ///
@@ -38,15 +40,15 @@ pub enum IntegraalError {
 /// ```rust
 /// # use integraal::{DomainDescriptor, ComputeMethod, FunctionDescriptor, Integraal, IntegraalError};
 /// # fn main() {
-/// // describe domain, function & computation method
+/// // describe domain
 /// let domain = DomainDescriptor::Uniform {
 ///     start: 0.0,
 ///     step: 0.00001,
 ///     n_step: 100_001,
 /// };
-///
-/// // decribe the function and numerical integration method
+/// // decribe the function
 /// let function = FunctionDescriptor::Closure(Box::new(|x: f64| 2.0 * x));
+/// // choose the numerical integration method
 /// let method = ComputeMethod::Trapezoid;
 ///
 /// // build the integral & compute it
@@ -57,7 +59,10 @@ pub enum IntegraalError {
 /// ```
 #[derive(Default)]
 pub struct Integraal<'a, X: Scalar> {
+    /// Domain over which the function is integrated.
     pub(crate) domain: Option<DomainDescriptor<'a, X>>,
+    /// Function to integrate.
     pub(crate) function: Option<FunctionDescriptor<X>>,
+    /// Numerical integration method used for value approximation.
     pub(crate) method: Option<ComputeMethod>,
 }

integraal/src/structure/implementations.rs

@@ -40,7 +40,7 @@ impl<'a, X: Scalar> Integraal<'a, X> {
     /// # Return / Errors
     ///
     /// This method returns a `Result` taking the following values:
-    /// - `Ok(f64)` -- The computation was successfuly done
+    /// - `Ok(X: Scalar)` -- The computation was successfuly done
     /// - `Err(IntegraalError)` -- The computation failed for the reason specified by the enum.
     pub fn compute(&mut self) -> Result<X, IntegraalError> {
         if self.domain.is_none() | self.function.is_none() | self.method.is_none() {