docs: fix a collection of inconsistent function and trait documentation

Author: mobiusklein

Cargo.toml

@@ -35,6 +35,15 @@ required-features = ["parallelism", "mzsignal", "nalgebra"]
 [[example]]
 name = "random_access_iter"
 required-features = ["nalgebra"]
+doc-scrape-examples = true
+
+[[example]]
+name = "mzinfo"
+doc-scrape-examples = true
+
+[[example]]
+name = "mzconvert"
+doc-scrape-examples = true
 
 [lib]
 name = "mzdata"

src/io/mzml/reader.rs

@@ -440,6 +440,7 @@ impl<C: CentroidLike, D: DeconvolutedCentroidLike> Default for MzMLSpectrumBuild
 impl<C: CentroidLike, D: DeconvolutedCentroidLike> XMLParseBase for MzMLSpectrumBuilder<'_, C, D> {}
 impl<C: CentroidLike, D: DeconvolutedCentroidLike> CVParamParse for MzMLSpectrumBuilder<'_, C, D> {}
 
+#[doc(hidden)]
 impl<'inner, C: CentroidLike, D: DeconvolutedCentroidLike>
     SpectrumBuilding<'inner, C, D, MultiLayerSpectrum<C, D>> for MzMLSpectrumBuilder<'inner, C, D>
 {
@@ -1086,6 +1087,7 @@ impl<C: CentroidLike + BuildFromArrayMap, D: DeconvolutedCentroidLike + BuildFro
     }
 }
 
+#[doc(hidden)]
 impl<'a, C: CentroidLike, D: DeconvolutedCentroidLike> From<MzMLSpectrumBuilder<'a, C, D>>
     for CentroidSpectrumType<C>
 where
@@ -1099,6 +1101,7 @@ where
     }
 }
 
+#[doc(hidden)]
 impl<'a, C: CentroidLike, D: DeconvolutedCentroidLike> From<MzMLSpectrumBuilder<'a, C, D>>
     for MultiLayerSpectrum<C, D>
 {
@@ -1109,6 +1112,7 @@ impl<'a, C: CentroidLike, D: DeconvolutedCentroidLike> From<MzMLSpectrumBuilder<
     }
 }
 
+#[doc(hidden)]
 impl<'a> From<MzMLSpectrumBuilder<'a>> for RawSpectrum {
     fn from(val: MzMLSpectrumBuilder<'a>) -> Self {
         let mut spec = Spectrum::default();

src/params.rs

@@ -1233,7 +1233,7 @@ macro_rules! find_param_method {
 #[macro_export]
 macro_rules! curie {
     (MS:$acc:literal) => {
-        $crate::params::CURIE::new($crate::params::ControlledVocabulary::MS, $acc)
+        $crate::params::CURIE { controlled_vocabulary: $crate::params::ControlledVocabulary::MS, accession: $acc }
     };
     (UO:$acc:literal) => {
         $crate::params::CURIE { controlled_vocabulary: $crate::params::ControlledVocabulary::UO, accession: $acc }

src/spectrum/chromatogram.rs

@@ -160,7 +160,7 @@ pub trait ChromatogramLike: ParamDescribed {
         self.description().ms_level
     }
 
-    /// Access the native ID string for the spectrum
+    /// Access the native ID string for the chromatogram
     #[inline]
     fn id(&self) -> &str {
         &self.description().id
@@ -171,7 +171,7 @@ pub trait ChromatogramLike: ParamDescribed {
         self.description().chromatogram_type
     }
 
-    /// Access the index of the spectrum in the source file
+    /// Access the index of the chromatogram in the source file
     #[inline]
     fn index(&self) -> usize {
         self.description().index

src/spectrum/spectrum_types.rs

@@ -1137,6 +1137,7 @@ where
         }
     }
 
+    /// Construct a [`MultiLayerSpectrum`] with `description` and the provided raw data arrays
     pub fn from_arrays_and_description(
         arrays: BinaryArrayMap,
         description: SpectrumDescription,
@@ -1148,6 +1149,7 @@ where
         }
     }
 
+    /// Construct a [`MultiLayerSpectrum`] with `description` and *no* peak data of any kind
     pub fn from_description(description: SpectrumDescription) -> Self {
         Self {
             description,
@@ -1167,13 +1169,21 @@ where
         }
     }
 
+    /// Converts an arbitrary [`SpectrumLike`] type into a [`MultiLayerSpectrum`] with the same
+    /// peak types.
+    ///
+    /// This is a thin wrapper around [`SpectrumLike::into_peaks_and_description`] and [`MultiLayerSpectrum::from_peaks_data_levels_and_description`]
     pub fn from_spectrum_like<S: SpectrumLike<C, D>>(spectrum: S) -> Self {
         let (peaks, description) = spectrum.into_peaks_and_description();
         Self::from_peaks_data_levels_and_description(peaks, description)
     }
 
-    /// Convert a [`DeconvolutedSpectrumType`] into a [`MultiLayerSpectrum`] over any peak type, but
-    /// recode the peak list as [`DataArray`], potentially losing information.
+    /// Convert a [`MultiLayerSpectrum`] with one set of peak types to another with any peak type, but
+    /// recode the peak list as [`DataArray`] as an intermediary, potentially losing information.
+    ///
+    /// ## Note
+    /// Peak data is not actually reconstructed from the intermediate data arrays. If that is desired,
+    /// call [`MultiLayerSpectrum::try_build_peaks`]
     pub fn reinterpret<C1, D1>(self) -> MultiLayerSpectrum<C1, D1>
     where
         C1: CentroidLike + BuildArrayMapFrom + BuildFromArrayMap,