Ship XML documentation so consumers get tooltips, and point the README at the wiki

README.md

@@ -15,41 +15,32 @@ NuGet packages are released here: https://www.nuget.org/packages/mzLib/
 
 GitHub release tags are recoreded here: https://github.com/smith-chem-wisc/mzLib/releases
 
-# Usage
-## Reading Spectra Files
-To read Thermo or mzML files, use
-```
-ThermoStaticData staticThermo = ThermoStaticData.LoadAllStaticData(@"spectra.raw");
-ThermoDynamicData dynamicThermo = ThermoDynamicData.InitiateDynamicConnection(@"spectra.raw")
-Mzml mzmlFile = Mzml.LoadAllStaticData(@"spectra.mzML");
-```
-Both filetypes implement the same interface that has all of the necessary functionality to interact with spectra files:
-```
-IMsDataFile<IMsDataScan<IMzSpectrum<IMzPeak>>> thermoFile = new ThermoRawFile(@"spectra.RAW");
-IMsDataFile<IMsDataScan<IMzSpectrum<IMzPeak>>> mzmlFile = new Mzml(@"spectra.mzML");
-```
-## Loading Databases From Online Sources
-```
-Loaders.LoadElements("elements.dat"); // void, loads elements into static PeriodicTable class 
-IEnumerable<ModificationWithLocation> unimodMods = Loaders.LoadUnimod("unimod.dat");
-IEnumerable<ModificationWithLocation> uniprotMods = Loaders.LoadUniprot("uniprot.dat");
-```
-## Reading Protein Database Files
-To read .fasta, .xml, or .xml.gz files, use 
-```
-List<Protein> proteins = ProteinDbLoader.LoadProteinDb("proteins.xml", generateDecoys, allKnownModifications, IsContaminant, out unknownModifications);
-```
-The parameters are:
-* ```bool generateDecoys``` True if wish to generate decoy proteins.
-* ```IDictionary<string, IList<Modification>> allKnownModifications``` Dictionary of modifications with keys that correspond to modifications in the xml file.
-* ```bool IsContaminant``` True if it is a contaminant database
-* ```out Dictionary<string, Modification> unknownModifications``` An auxiliary output of modifications that were in the xml file but are not known.
-
-## Reading Modification Files
-To load modifications from ptmlist formatted files use
-```
-IEnumerable<ModificationWithLocation> ptms = PtmListLoader.ReadMods("ptms.txt")
-```
+# Documentation
+
+**The [mzLib wiki](https://github.com/smith-chem-wisc/mzLib/wiki) is the usage documentation, and it is
+kept current.** Among other things it covers:
+
+- [Reading mass spectrometry files](https://github.com/smith-chem-wisc/mzLib/wiki/File-Reading:-Mass-Spec)
+- [Reading search-result formats](https://github.com/smith-chem-wisc/mzLib/wiki/File-Reading:-Result-Formats)
+- [Reading sequence databases](https://github.com/smith-chem-wisc/mzLib/wiki/File-Reading:-Sequence-Databases)
+- [Chemistry](https://github.com/smith-chem-wisc/mzLib/wiki/Chemistry) and [Mass Spectrometry](https://github.com/smith-chem-wisc/mzLib/wiki/Mass-Spectrometry)
+- Omics: [base foundation](https://github.com/smith-chem-wisc/mzLib/wiki/Omics:-Base-Foundation), [digestion](https://github.com/smith-chem-wisc/mzLib/wiki/Omics:-Digestion), [modifications](https://github.com/smith-chem-wisc/mzLib/wiki/Omics:-Modifications), [fragmentation](https://github.com/smith-chem-wisc/mzLib/wiki/Omics:-Fragmentation), [decoy generation](https://github.com/smith-chem-wisc/mzLib/wiki/Omics:-Decoy-Generation), [proteomics](https://github.com/smith-chem-wisc/mzLib/wiki/Omics:-Proteomics)
+
+The package also ships XML documentation, so mzLib types and members have tooltips in your IDE.
+
+Usage examples used to live in this file. They were removed rather than rewritten because they had
+drifted out of date - one called a `ProteinDatabaseLoader` type that no longer exists - and a second
+copy of the documentation is a second thing to keep current. The wiki is the single place now.
+
+# Contributing
+
+Tests live in `mzLib/Test`. Run them with
+`dotnet test mzLib/Test/Test.csproj --filter "Category!=ExternalService"`; the `ExternalService`
+category covers tests that reach live services such as UniProt, and is deliberately kept out of the
+required build so that an outage elsewhere cannot fail a pull request.
+
 # License
-Code heavily borrowed from https://github.com/dbaileychess/CSMSL and distrubuted under the appropriate license, LGPL.
+Code heavily borrowed from https://github.com/dbaileychess/CSMSL and distributed under the appropriate license, LGPL.
 
+mzLib additionally redistributes third-party data files and native libraries whose licences are
+separate from its own; see [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

mzLib/Chromatography/RetentionTimePrediction/CZE/CZERetentionTimePredictor.cs

@@ -20,7 +20,7 @@ public class CZERetentionTimePredictor : RetentionTimePredictor
     /// <summary>
     /// Initializes a new CZE predictor with custom instrument parameters
     /// </summary>
-    /// <param name="modHandlingMode">How to handle modifications (CZE uses mass, so this mainly affects which sequence to use)</param>
+    /// <param name="sequenceHandlingMode">How to handle modifications (CZE uses mass, so this mainly affects which sequence to use)</param>
     /// <param name="columnLengthMeters">Total capillary length in meters (default: 1.0m)</param>
     /// <param name="voltsPerMeter">Applied voltage gradient in V/m (default: 300,000 V/m)</param>
     public CZERetentionTimePredictor(

mzLib/Chromatography/RetentionTimePrediction/SSRCalc/SSRCalc3.cs

@@ -1173,7 +1173,7 @@ private double EvalH2pattern(string pattern, string testsq, int posn, char etype
     /// <param name="acid">Central amino acid.</param>
     /// <param name="lp">Left-flanking amino acid.</param>
     /// <param name="rp">Right-flanking amino acid.</param>
-    /// <param name="ct">Connector type ("--", "<-", or "->").</param>
+    /// <param name="ct">Connector type ("--", "&lt;-", or "-&gt;").</param>
     /// <param name="far1">Far-left amino acid for offset patterns.</param>
     /// <param name="far2">Far-right amino acid for offset patterns.</param>
     /// <returns>Connection multiplier (0 = incompatible, >0 = compatible).</returns>

mzLib/Directory.Build.props

@@ -5,6 +5,32 @@
          net10.0, since that is the default from net9.0 on; stated anyway so retargeting a project
          downwards cannot quietly reduce auditing to direct dependencies only. -->
     <NuGetAuditMode>all</NuGetAuditMode>
+
+    <!-- Emit the XML documentation file next to each assembly, and ship it in the package, so that
+         consumers get tooltips for mzLib types in their IDE. Roughly 1,900 <summary> blocks already
+         exist across the tree and none of them reached anyone outside this repository before now. -->
+    <!-- Only for projects that ship. An XML documentation file for a test or benchmark assembly
+         serves nobody, and generating it there was surfacing 60 of the 103 doc-comment warnings in
+         code no consumer ever sees. -->
+    <GenerateDocumentationFile Condition="'$(MSBuildProjectName)' != 'Test' and '$(MSBuildProjectName)' != 'Development'">true</GenerateDocumentationFile>
+
+    <!-- Turning documentation generation on turns on seven doc-comment diagnostics. Two are
+         suppressed, on the line between "incomplete" and "wrong":
+           CS1591 missing XML comment for a public type or member - 248 of 930 public types have none,
+                  so this would bury every other warning. Worth filling in, not worth hiding the build.
+           CS1573 a parameter has no matching param tag - partial documentation is still useful
+                  documentation, and the tooltip renders.
+         The rest are left visible, because each one means a comment renders wrongly or not at all,
+         which defeats the point of shipping the file:
+           CS1570 badly formed XML                CS1587 comment not on a valid language element
+           CS1572 param tag, no such parameter    CS1711 typeparam tag, no such type parameter
+           CS1734 paramref, no such parameter     CS1574 cref that does not resolve
+           CS0419 ambiguous cref
+         All are at 0 except CS0419, which sits at 24. Those do resolve, just to an unspecified
+         overload, so the link works and only the signature is arbitrary.
+         Counts come from a non-incremental build; an incremental one hides warnings from
+         dependency projects it did not rebuild. -->
+    <NoWarn>$(NoWarn);CS1591;CS1573</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

mzLib/FlashLFQ/Bayesian Protein Quantification/PairedProteinQuantResult.cs

@@ -101,9 +101,9 @@ public void EstimateProteinFoldChange(int? randomSeed, int nBurnin, int n, doubl
             //        "False Discovery Rate" + "\t\t";
         }
 
-        /// <summary>
-        /// Computes a list of fold-change measurements between the constituent peptides of this protein between the control and treatment condition.
-        /// </summary>
+        // <summary>
+        // Computes a list of fold-change measurements between the constituent peptides of this protein between the control and treatment condition.
+        // </summary>
         //private List<(Peptide peptide, List<double> foldChanges)> GetPeptideFoldChanges(bool useSharedPeptides, FlashLfqResults flashLfqResults,
         //    Dictionary<(Peptide, string, int), (double, DetectionType)> PeptideToSampleQuantity)
         //{
@@ -141,10 +141,10 @@ public void EstimateProteinFoldChange(int? randomSeed, int nBurnin, int n, doubl
         //    return allPeptideFoldChanges;
         //}
 
-        /// <summary>
-        /// Computes the log-fold change between two intensities. If there is an error (e.g., one of the intensities is zero), 
-        /// null is returned.
-        /// </summary>
+        // <summary>
+        // Computes the log-fold change between two intensities. If there is an error (e.g., one of the intensities is zero), 
+        // null is returned.
+        // </summary>
         //private double? GetLogFoldChange(double intensity1, double intensity2)
         //{
         //    double logFoldChange = Math.Log(intensity2, 2) - Math.Log(intensity1, 2);

mzLib/FlashLFQ/ChromatographicPeak.cs

@@ -8,6 +8,12 @@
 
 namespace FlashLFQ
 {
+    /// <summary>
+    /// An integrated elution peak for one identified species in one spectra file: the isotopic envelopes
+    /// that were grouped together, the resulting intensity, and how the peak was found. Peaks whose
+    /// <see cref="DetectionType"/> is MBR were transferred from another file by match-between-runs rather
+    /// than identified in this one.
+    /// </summary>
     public class ChromatographicPeak : IEquatable<ChromatographicPeak>
     {
         public double Intensity { get; private set; }
@@ -38,9 +44,7 @@ public ChromatographicPeak(Identification id, SpectraFileInfo fileInfo, Detectio
         /// overloaded constructor for Isobaric_ambiguity peaks. In this case, the peak is identified by multiple identifications
         /// </summary>
         /// <param name="ids"></param>
-        /// <param name="isMbrPeak"></param>
         /// <param name="fileInfo"></param>
-        /// <param name="randomRt"></param>
         public ChromatographicPeak(List<Identification> ids, SpectraFileInfo fileInfo, DetectionType detectionType)
         { 
             SplitRT = 0;

mzLib/FlashLFQ/FlashLfqEngine.cs

@@ -21,6 +21,12 @@
 
 namespace FlashLFQ
 {
+    /// <summary>
+    /// Label-free quantification: takes identifications from a search, finds and integrates their
+    /// chromatographic peaks in each spectra file, optionally transfers identifications between files by
+    /// match-between-runs, then rolls peaks up to peptide and protein intensities.
+    /// Construct it with the identifications and options, then call <see cref="Run"/> once.
+    /// </summary>
     public class FlashLfqEngine
     {
         public FlashLfqParameters FlashParams { get; init; }
@@ -817,7 +823,6 @@ internal RtInfo PredictRetentionTime(
         /// Returns a pseudo-randomly selected peak that does not have the same mass as the donor
         /// </summary>
         /// <param name="peaksOrderedByMass"></param>
-        /// <param name="donorPeakPeakfindingMass"> Will search for a peak at least 5 Da away from the peakfinding mass </param>
         /// <returns></returns>
         internal ChromatographicPeak GetRandomPeak(
             List<ChromatographicPeak> peaksOrderedByMass,
@@ -1160,7 +1165,6 @@ private void AddPeakToConcurrentDict(ConcurrentDictionary<string, ConcurrentDict
         /// <param name="rtInfo"> RtInfo object containing the predicted retention time for the acceptor peak and the width of the expected RT window </param>
         /// <param name="fileSpecificTol"> Ppm Tolerance specific to the acceptor file</param>
         /// <param name="donorPeak"> The donor peak. Acceptor peaks are presumed to represent the same peptide as the donor peak</param>
-        /// <param name="matchBetweenRunsIdentifiedPeaksThreadSpecific"> A dictionary containing peptide sequences and their associated mbr peaks </param>
         internal void FindAllAcceptorPeaks(
             SpectraFileInfo acceptorFile, 
             MbrScorer scorer,
@@ -1243,7 +1247,6 @@ internal void FindAllAcceptorPeaks(
         /// <param name="acceptorFile"></param>
         /// <param name="mbrTol"></param>
         /// <param name="rtInfo"></param>
-        /// <param name="rtScoringDistribution"></param>
         /// <param name="z"></param>
         /// <param name="chargeEnvelopes"></param>
         /// <returns> An acceptor chromatographic peak, unless the peak found was already linked to an MS/MS id, in which case it return null. </returns>
@@ -1992,8 +1995,8 @@ internal XIC BuildXIC(List<Identification> ids, SpectraFileInfo spectraFile, boo
         /// The ChromPeaks will be stored in chromPeaksInThisSequence
         /// For example, we have four invaild peak in the XIC, then we look at the first peak, generate chormPeak from each file. The dictionary will be like: peak1: [chromPeak (run 1), chromPeak (run 2), chromPeak (run 3)...]
         /// </summary>
-        /// <param name="peaksInOneXIC"> The time window for the valid peak, format is <time < start, end>> </start></param>
-        /// <param name="chromPeaksInThisSequence"> The resilt will store the inforamtion</param>
+        /// <param name="sharedPeak"> The time window for the valid peak, format is time &lt; start, end &gt; </param>
+        /// <param name="chromPeaksInSharedPeak"> The resilt will store the inforamtion</param>
         internal void CollectChromPeakInRuns(PeakRegion sharedPeak, List<ChromatographicPeak> chromPeaksInSharedPeak, XICGroups xICGroups)
         {
             foreach (var xic in xICGroups)
@@ -2063,8 +2066,7 @@ public bool Within(double time, double start, double end)
         /// </summary>
         /// <param name="rtInfo">Retention information</param>
         /// <param name="xic">The searched XIC</param>
-        /// <param name="idForChrom"></param>
-        /// <param name="isMBR"></param>
+        /// <param name="idsForChrom"></param>
         /// <returns></returns>
         internal ChromatographicPeak FindChromPeak(Tuple<double, double, double> rtInfo, XIC xic, List<Identification> idsForChrom, DetectionType detectionType)
         {

mzLib/FlashLFQ/Identification.cs

@@ -4,6 +4,11 @@
 
 namespace FlashLFQ
 {
+    /// <summary>
+    /// One identification handed to FlashLFQ as a starting point for quantification: a sequence observed
+    /// in a particular file at a particular retention time, mass and charge. FlashLFQ does not identify
+    /// anything itself - these come from a search engine - and it uses them as seeds for peak finding.
+    /// </summary>
     public class Identification
     {
         public readonly string BaseSequence;

mzLib/FlashLFQ/IntensityNormalizationEngine.cs

@@ -317,10 +317,10 @@ private void NormalizeBioreps()
             }
         }
 
-        /// <summary>
-        /// This method takes a list of peptides and creates a subset list of peptides to normalize with, to avoid
-        /// excessive computation time in normalization functions.
-        /// </summary>
+        // <summary>
+        // This method takes a list of peptides and creates a subset list of peptides to normalize with, to avoid
+        // excessive computation time in normalization functions.
+        // </summary>
         //private List<Peptide> SubsetData(List<Peptide> initialList, List<SpectraFileInfo> spectraFiles)
         //{
         //    List<SpectraFileInfo>[] bothBioreps = new List<SpectraFileInfo>[2];

mzLib/FlashLFQ/IsoTracker/IsoTrackerIdFilter.cs

@@ -14,7 +14,6 @@ public class IsoTrackerIdFilter
         /// Directly use the motif string to create a SearchingTarget
         /// </summary>
         /// <param name="motifs"></param>
-        /// <param name="option2"></param>
         public IsoTrackerIdFilter(List<char> motifs)
         {
             TargetMotifs = new List<ModificationMotif>();

mzLib/FlashLFQ/IsoTracker/XIC.cs

@@ -117,7 +117,7 @@ internal void BuildLinearSpline()
         /// <summary>
         /// calculate the retention time shift among the reference. Then store the value in the RtShift property.
         /// </summary>
-        /// <param name="xicToAlign"> The reference XIC</param>
+        /// <param name="referenceXIC"> The reference XIC</param>
         /// <param name="resolution"> The number of the timePoint for X-correlation </param>
         /// <returns> The retention to shift to align to the reference </returns>
         public double AlignXICs(XIC referenceXIC, int resolution = 1000)
@@ -171,7 +171,7 @@ public double AlignXICs(XIC referenceXIC, int resolution = 1000)
         /// Try to smooth the XIC by averaging the intensity of the points (weight averaging then sum averaging).
         /// Using the smoothedXIC to generate the cubic spline date for Extremum finding.
         /// </summary>
-        /// <param name="pointsToAverage"> Should be odds number. The number of points to average for smoothing the XIC </param>
+        /// <param name="smoothDegree"> Should be odds number. The number of points to average for smoothing the XIC </param>
         /// <exception cref="ArgumentException"></exception>
         public void BuildSmoothedCubicSpline(int smoothDegree)
         {

mzLib/FlashLFQ/IsoTracker/XICGroups.cs

@@ -188,7 +188,7 @@ private void SharePeakTrimming(double cutOff = 0.3)
         /// Generate the shared extrema information (retention and intensity) in the reference XIC
         /// </summary>
         /// <param name="reference"></param>
-        /// <param name="sharedExtre"></param>
+        /// <param name="sharedExtrema"></param>
         public void ProjectExtremaInRef(XIC reference, List<Extremum> sharedExtrema)
         {
             ExtremaInRef = new Dictionary<double, double>();

mzLib/FlashLFQ/Peptide.cs

@@ -5,6 +5,12 @@
 
 namespace FlashLFQ
 {
+    /// <summary>
+    /// One peptide sequence's quantification across every spectra file: its intensity per file, how that
+    /// intensity was obtained per file, and the protein groups it belongs to. This is the roll-up of the
+    /// <see cref="ChromatographicPeak"/> objects sharing a sequence, and is what
+    /// QuantifiedPeptides.tsv is written from.
+    /// </summary>
     public class Peptide
     {
         public readonly string Sequence;

mzLib/MassSpectrometry/MzSpectra/SpectralSimilarity.cs

@@ -108,8 +108,7 @@ private static double[] Normalize(double[] spectrum, SpectrumNormalizationScheme
         /// NOTE: ALL THEORETICAL MZ VALUES ARE USED TO CREATE AN INTENSITY PAIR. This prevents high similarity scores from
         /// only a handful of peaks.
         /// </summary>
-        /// <param name="keepAllExperimentalPeaks"></param>
-        /// <param name="keepAllTheoreticalPeaks"></param>
+        /// <param name="allPeaks"></param>
         /// <param name="experimentalYArray"></param>
         /// <param name="theoreticalYArray"></param>
         /// <returns></returns>

mzLib/MassSpectrometry/PeakIndexing/ExtractedIonChromatogram.cs

@@ -53,7 +53,6 @@ public void SetNormalizedPeakIntensities()
         /// <summary>
         /// Determines whether a peak should be cut based on the intensity of the surrounding time points.
         /// </summary>
-        /// <typeparam name="T">The type of the time points, which must implement ISingleScanDatum.</typeparam>
         /// <param name="timePoints">The list of time points</param>
         /// <param name="apexTimepointIndex">The index of the apex (most intense, best, whatever) in the list of time points.</param>
         /// <param name="discriminationFactorToCutPeak">The discrimination factor to determine if the peak should be cut. Default is 0.6.</param>