Improved examples in docs

benches/bench.rs

@@ -5,7 +5,7 @@
 // http://opensource.org/licenses/MIT>, at your option. This file may not be
 // copied, modified, or distributed except according to those terms.
 
-//! TODO
+//! Benchmarks
 
 #![feature(test)]
 

src/coordinates.rs

@@ -7,9 +7,9 @@
 
 use crate::SphrsFloat;
 
-/// SHCoordinates trait
+/// Definition of coordinates
 ///
-/// Every coordinate used in sphrs must implement this trait.
+/// Coordinates used in sphrs must implement this trait.
 pub trait SHCoordinates<T>: Sized {
     /// Return `theta` (spherical coordinates)
     fn theta(&self) -> T;

src/float.rs

@@ -9,6 +9,6 @@ use num::{Float, FromPrimitive};
 use num_traits::float::FloatConst;
 use std::fmt::Debug;
 
-/// Trait alias to simplify common trait bounds
+/// Trait alias for trait bounds on floats
 pub trait SphrsFloat: Float + FloatConst + FromPrimitive + Debug {}
 impl<I> SphrsFloat for I where I: Float + FloatConst + FromPrimitive + Debug {}

src/lib.rs

@@ -45,28 +45,44 @@
 //! The `eval` method is part of the [`SHEval`] trait and as such this trait must be in scope.
 //!
 //! ```rust
-//! use sphrs::{RealSH, Coordinates, SHEval};
+//! use sphrs::{Coordinates, RealSH, SHEval};
 //!
-//! let sh = RealSH::Spherical;
+//! // l = 2
 //! let degree = 2;
+//! // m = 1
 //! let order = 1;
-//! let p = Coordinates::cartesian(1.0, 0.0, 0.0);
+//!
+//! // Define the position where the SH will be evaluated at
+//! // in Cartesian coordinates
+//! let p = Coordinates::cartesian(1.0, 0.2, 1.4);
+//!
+//! // Compute the real-valued SH value at `p` for l = 2, m = 1
 //! let computed_sh = RealSH::Spherical.eval(degree, order, &p);
+//!
 //! println!("SH ({}, {}): {:?}", degree, order, computed_sh);
 //! ```
 //!
 //! This library can also compute [`HarmonicsSet`]s which contains all spherical/solid harmonics
 //! up to a given order.
 //!
 //! The following example shows how to compute complex spherical harmonics up to third order at
-//! the spherical coordinates (1.0, 0.8, 0.4):
+//! the spherical coordinates (r, theta, phi) = (1.0, 0.8, 0.4):
 //!
 //! ```rust
-//! use sphrs::{ComplexSH, HarmonicsSet, Coordinates};
+//! use sphrs::{ComplexSH, Coordinates, HarmonicsSet};
+//!
+//! // l = 3
 //! let degree = 3;
+//!
+//! // Create the harmonics set (in this case for complex SH)
 //! let sh = HarmonicsSet::new(degree, ComplexSH::Spherical);
+//!
+//! // Position in spherical coordinates where the set is evaluated at
 //! let p = Coordinates::spherical(1.0, 0.8, 0.4);
-//! let set = sh.eval(&p); // Is of type Vec<_>
+//!
+//! // Evaluate. Returns a `Vec<f64>`
+//! let set = sh.eval(&p);
+//!
 //! println!("SH up to degree {}: {:?}", degree, set);
 //! ```
 //!
@@ -86,7 +102,7 @@
 //!
 //! # Advanced features
 //!
-//! Feel free to use the low level functions linked at the bottom of this page directly.
+//! Feel free to directly use the low level functions linked at the bottom of this page.
 //!
 //! # Acknowledgements
 //!

src/sh/mod.rs

@@ -21,7 +21,9 @@ use crate::coordinates::SHCoordinates;
 use crate::SphrsFloat;
 use num_complex::Complex;
 
-/// SH eval trait (TODO)
+/// Harmonics evaluation trait
+///
+/// Every kind of harmonics needs to implement this in order to be usable with [`HarmonicsSet`].
 pub trait SHEval<T> {
     /// Output type
     type Output;