doc: improvements for SampleFormat (#885)

* doc: fix SampleFormat inconsistencies
* doc: add more documentation for SampleFormat

Author: phip1611

src/samples_formats.rs

@@ -4,47 +4,61 @@ use wasm_bindgen::prelude::*;
 
 pub use dasp_sample::{FromSample, Sample, I24, I48, U24, U48};
 
-/// Format that each sample has.
+/// Format that each sample has. Usually, this corresponds to the sampling
+/// depth of the audio source. For example, 16 bit quantized samples can be
+/// encoded in `i16` or `u16`. Note that the sampling depth is not directly
+/// visible for formats where [`is_float`] is true.
+///
+/// Also note that the backend must support the encoding of the quantized
+/// samples in the given format, as there is no generic transformation from one
+/// format into the other done inside the frontend-library code. You can query
+/// the supported formats by using [`supported_input_configs`].
+///
+/// A good rule of thumb is to use [`SampleFormat::I16`] as this covers typical
+/// music (WAV, MP3) as well as typical audio input devices on most platforms,
+///
+/// [`is_float`]: SampleFormat::is_float
+/// [`supported_input_configs`]: crate::Device::supported_input_configs
 #[cfg_attr(target_os = "emscripten", wasm_bindgen)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[non_exhaustive]
 pub enum SampleFormat {
-    /// `i8` with a valid range of 'u8::MIN..=u8::MAX' with `0` being the origin
+    /// `i8` with a valid range of `i8::MIN..=i8::MAX` with `0` being the origin.
     I8,
 
-    /// `i16` with a valid range of 'u16::MIN..=u16::MAX' with `0` being the origin
+    /// `i16` with a valid range of `i16::MIN..=i16::MAX` with `0` being the origin.
     I16,
 
     // /// `I24` with a valid range of '-(1 << 23)..(1 << 23)' with `0` being the origin
     // I24,
-    /// `i32` with a valid range of 'u32::MIN..=u32::MAX' with `0` being the origin
+    /// `i32` with a valid range of `i32::MIN..=i32::MAX` with `0` being the origin.
     I32,
 
     // /// `I24` with a valid range of '-(1 << 47)..(1 << 47)' with `0` being the origin
     // I48,
-    /// `i64` with a valid range of 'u64::MIN..=u64::MAX' with `0` being the origin
+    /// `i64` with a valid range of `i64::MIN..=i64::MAX` with `0` being the origin.
     I64,
 
-    /// `u8` with a valid range of 'u8::MIN..=u8::MAX' with `1 << 7 == 128` being the origin
+    /// `u8` with a valid range of `u8::MIN..=u8::MAX` with `1 << 7 == 128` being the origin.
     U8,
 
-    /// `u16` with a valid range of 'u16::MIN..=u16::MAX' with `1 << 15 == 32768` being the origin
+    /// `u16` with a valid range of `u16::MIN..=u16::MAX` with `1 << 15 == 32768` being the origin.
     U16,
 
     // /// `U24` with a valid range of '0..16777216' with `1 << 23 == 8388608` being the origin
     // U24,
-    /// `u32` with a valid range of 'u32::MIN..=u32::MAX' with `1 << 31` being the origin
+    /// `u32` with a valid range of `u32::MIN..=u32::MAX` with `1 << 31` being the origin.
     U32,
 
     // /// `U48` with a valid range of '0..(1 << 48)' with `1 << 47` being the origin
     // U48,
-    /// `u64` with a valid range of 'u64::MIN..=u64::MAX' with `1 << 63` being the origin
+    /// `u64` with a valid range of `u64::MIN..=u64::MAX` with `1 << 63` being the origin.
     U64,
 
-    /// `f32` with a valid range of `-1.0..1.0` with `0.0` being the origin
+    /// `f32` with a valid range of `-1.0..1.0` with `0.0` being the origin.
     F32,
 
-    /// `f64` with a valid range of -1.0..1.0 with 0.0 being the origin
+    /// `f64` with a valid range of `-1.0..1.0` with `0.0` being the origin.
     F64,
 }