refactor operations and utils; update XML comments

NWaves/Audio/ByteConverter.cs

@@ -1,12 +1,12 @@
 namespace NWaves.Audio
 {
     /// <summary>
-    /// Static class providing methods for conversion between PCM bytes and float[] data.
+    /// Provides methods for conversion between PCM bytes and float[] data.
     /// </summary>
     public static class ByteConverter
     {
         /// <summary>
-        /// Convert Pcm_8bit <paramref name="bytes"/> to arrays of <paramref name="floats"/>.
+        /// Converts Pcm_8bit <paramref name="bytes"/> to arrays of <paramref name="floats"/>.
         /// </summary>
         /// <param name="bytes">Array of bytes</param>
         /// <param name="floats">Arrays of floats</param>
@@ -38,7 +38,7 @@ public static void ToFloats8Bit(byte[] bytes, float[][] floats, bool normalize =
         }
 
         /// <summary>
-        /// Convert arrays of <paramref name="floats"/> to Pcm_8bit <paramref name="bytes"/>.
+        /// Converts arrays of <paramref name="floats"/> to Pcm_8bit <paramref name="bytes"/>.
         /// </summary>
         /// <param name="bytes">Array of bytes</param>
         /// <param name="floats">Arrays of floats</param>
@@ -70,7 +70,7 @@ public static void FromFloats8Bit(float[][] floats, byte[] bytes, bool normalize
         }
 
         /// <summary>
-        /// Convert Pcm_16bit <paramref name="bytes"/> to arrays of <paramref name="floats"/> (little-endian or big-endian).
+        /// Converts Pcm_16bit <paramref name="bytes"/> to arrays of <paramref name="floats"/> (little-endian or big-endian).
         /// </summary>
         /// <param name="bytes">Array of bytes</param>
         /// <param name="floats">Arrays of floats</param>
@@ -130,7 +130,7 @@ public static void ToFloats16Bit(byte[] bytes, float[][] floats, bool normalize
         }
 
         /// <summary>
-        /// Convert arrays of <paramref name="floats"/> to Pcm_16bit <paramref name="bytes"/> (little-endian or big-endian).
+        /// Converts arrays of <paramref name="floats"/> to Pcm_16bit <paramref name="bytes"/> (little-endian or big-endian).
         /// </summary>
         /// <param name="bytes">Array of bytes</param>
         /// <param name="floats">Arrays of floats</param>

NWaves/Audio/Interfaces/IAudioContainer.cs

@@ -9,12 +9,12 @@ namespace NWaves.Audio.Interfaces
     public interface IAudioContainer
     {
         /// <summary>
-        /// Get the list of discrete signals in container.
+        /// Gets the list of discrete signals in container.
         /// </summary>
         List<DiscreteSignal> Signals { get; }
 
         /// <summary>
-        /// Return container's signal using indexing based on channel type.
+        /// Gets the signal from container using indexing scheme based on channel type.
         /// </summary>
         /// <param name="channel">Channel (left, right, interleave, sum, average, or ordinary index)</param>
         DiscreteSignal this[Channels channel] { get; }

NWaves/Audio/Interfaces/IAudioPlayer.cs

@@ -9,12 +9,12 @@ namespace NWaves.Audio.Interfaces
     public interface IAudioPlayer
     {
         /// <summary>
-        /// Gets or sets sound volume (usually in range [0.0f, 1.0f]).
+        /// Gets or sets sound volume (usually in range [0..1]).
         /// </summary>
         float Volume { get; set; }
 
         /// <summary>
-        /// Play samples contained in <paramref name="signal"/> asynchronously.
+        /// Plays samples contained in <paramref name="signal"/> asynchronously.
         /// </summary>
         /// <param name="signal">Signal to play</param>
         /// <param name="startPos">Index of the first sample to play</param>
@@ -23,25 +23,25 @@ public interface IAudioPlayer
         Task PlayAsync(DiscreteSignal signal, int startPos = 0, int endPos = -1, short bitDepth = 16);
 
         /// <summary>
-        /// Play samples contained in WAV file (or some other source) asynchronously.
+        /// Plays samples contained in WAV file (or some other source) asynchronously.
         /// </summary>
         /// <param name="source">Path to WAV file (or other source) to play</param>
         /// <param name="startPos">Index of the first sample to play</param>
         /// <param name="endPos">Index of the last sample to play</param>
         Task PlayAsync(string source, int startPos = 0, int endPos = -1);
 
         /// <summary>
-        /// Pause playing audio.
+        /// Pauses playing audio.
         /// </summary>
         void Pause();
 
         /// <summary>
-        /// Resume playing audio.
+        /// Resumes playing audio.
         /// </summary>
         void Resume();
 
         /// <summary>
-        /// Stop playing audio.
+        /// Stops playing audio.
         /// </summary>
         void Stop();
     }

NWaves/Audio/Interfaces/IAudioRecorder.cs

@@ -6,15 +6,15 @@
     public interface IAudioRecorder
     {
         /// <summary>
-        /// Start recording audio with specific settings.
+        /// Starts recording audio with specific settings.
         /// </summary>
         /// <param name="samplingRate">Sampling rate</param>
         /// <param name="channelCount">Number of channels (1=mono, 2=stereo)</param>
         /// <param name="bitsPerSample">Number of bits per sample (8, 16, 24 or 32)</param>
         void StartRecording(int samplingRate, short channelCount, short bitsPerSample);
 
         /// <summary>
-        /// Stop recording audio and save recorded sound to file or any other destination.
+        /// Stops recording audio and saves recorded sound to file or any other destination.
         /// </summary>
         /// <param name="destination">Path to output file (destination)</param>
         void StopRecording(string destination);

NWaves/Audio/Mci/Mci.cs

@@ -4,7 +4,7 @@
 namespace NWaves.Audio.Mci
 {
     /// <summary>
-    /// Static class containing MCI functions imported from winmm.dll
+    /// Provides MCI functions imported from winmm.dll.
     /// </summary>
     public static class Mci
     {

NWaves/Audio/Mci/MciAudioPlayer.cs

@@ -40,12 +40,12 @@ public class MciAudioPlayer : IAudioPlayer
         private bool _isPaused;
 
         /// <summary>
-        /// Gets or sets audio volume (measured in percents from the range [0.0f, 1.0f]).
+        /// Gets or sets audio volume (measured in percents from the range [0..1]).
         /// </summary>
         public float Volume { get; set; }
 
         /// <summary>
-        /// Play audio contained in WAV file asynchronously.
+        /// Plays audio contained in WAV file asynchronously.
         /// </summary>
         /// <param name="source">Path to WAV file to play</param>
         /// <param name="startPos">Index of the first sample to play</param>
@@ -137,7 +137,7 @@ public Task PlayAsync(DiscreteSignal signal, int startPos = 0, int endPos = -1,
         }
 
         /// <summary>
-        /// Pause playing audio.
+        /// Pauses playing audio.
         /// </summary>
         public void Pause()
         {
@@ -157,7 +157,7 @@ public void Pause()
         }
 
         /// <summary>
-        /// Resume playing audio.
+        /// Resumes playing audio.
         /// </summary>
         public void Resume()
         {
@@ -176,7 +176,7 @@ public void Resume()
         }
 
         /// <summary>
-        /// Stop playing audio and close MCI device.
+        /// Stops playing audio and close MCI device.
         /// </summary>
         public void Stop()
         {

NWaves/Audio/Mci/MciAudioRecorder.cs

@@ -11,7 +11,7 @@ namespace NWaves.Audio.Mci
     public class MciAudioRecorder : IAudioRecorder
     {
         /// <summary>
-        /// Start recording audio with specific settings.
+        /// Starts recording audio with specific settings.
         /// </summary>
         /// <param name="samplingRate">Sampling rate</param>
         /// <param name="channelCount">Number of channels (1=mono, 2=stereo)</param>
@@ -40,7 +40,7 @@ public void StartRecording(int samplingRate = 44100, short channelCount = 1, sho
         }
 
         /// <summary>
-        /// Stop recording audio and save it to WAV file.
+        /// Stops recording audio and save it to WAV file.
         /// </summary>
         /// <param name="destination">Path to output WAV file containing recorded sound</param>
         public void StopRecording(string destination)

NWaves/Audio/WaveFile.cs

@@ -11,9 +11,9 @@ namespace NWaves.Audio
     /// <summary>
     /// <para>PCM WAV container.</para>
     /// <para>
-    /// <see cref="WaveFile"/> is not intended to be a "wrapper around the stream", or to acquire any resource 
-    /// (it doesn't affect the underlying stream). It's more like a "constructor of signals in memory based on data 
-    /// from the stream" and its lifetime is not synchronized with the stream whatsoever. 
+    /// <see cref="WaveFile"/> is not intended to be a wrapper around the stream, or to acquire any resource 
+    /// (it doesn't affect the underlying stream). It's more like a constructor of signals in memory based on data 
+    /// from the stream, and its lifetime is not synchronized with the stream whatsoever. 
     /// The synonym name of this class could be also "WaveContainer".
     /// </para>
     /// </summary>
@@ -25,7 +25,7 @@ public class WaveFile : IAudioContainer
         public List<DiscreteSignal> Signals { get; protected set; }
 
         /// <summary>
-        /// WAV header (WAVE format).
+        /// Gets WAV header (WAVE format).
         /// </summary>
         public WaveFormat WaveFmt { get; protected set; }
 
@@ -34,6 +34,16 @@ public class WaveFile : IAudioContainer
         /// </summary>
         public short[] SupportedBitDepths = { 8, 16, 24, 32 };
 
+        /// <summary>
+        /// Constructs WAV container by loading signals from <paramref name="waveStream"/>.
+        /// </summary>
+        /// <param name="waveStream">Input stream</param>
+        /// <param name="normalized">Normalize samples</param>
+        public WaveFile(Stream waveStream, bool normalized = true)
+        {
+            ReadWaveStream(waveStream, normalized);
+        }
+
         /// <summary>
         /// Constructs WAV container by loading signals from a byte array (i.e. byte content of WAV file).
         /// </summary>
@@ -62,17 +72,7 @@ public WaveFile(byte[] waveBytes, int index, bool normalized = true)
         }
 
         /// <summary>
-        /// Constructs WAV container by loading signals from <paramref name="waveStream"/>.
-        /// </summary>
-        /// <param name="waveStream">Input stream</param>
-        /// <param name="normalized">Normalize samples</param>
-        public WaveFile(Stream waveStream, bool normalized = true)
-        {
-            ReadWaveStream(waveStream, normalized);
-        }
-
-        /// <summary>
-        /// Read PCM WAV binary data and fill <see cref="Signals"/> and <see cref="WaveFmt"/> structure.
+        /// Reads PCM WAV binary data and fills <see cref="Signals"/> and <see cref="WaveFmt"/> structure.
         /// </summary>
         /// <param name="waveStream">Input stream of PCM WAV binary data</param>
         /// <param name="normalized">Normalize samples</param>
@@ -241,13 +241,13 @@ protected void ReadWaveStream(Stream waveStream, bool normalized = true)
         }
 
         /// <summary>
-        /// Construct WAV container by loading into it collection of <paramref name="signals"/> with given <paramref name="bitsPerSample"/>.
+        /// Constructs WAV container by loading into it collection of <paramref name="signals"/> with given <paramref name="bitsPerSample"/>.
         /// </summary>
         /// <param name="signals">Signals to be loaded into container</param>
         /// <param name="bitsPerSample">Bit depth</param>
         public WaveFile(IList<DiscreteSignal> signals, short bitsPerSample = 16)
         {
-            if (signals == null || !signals.Any())
+            if (signals is null || !signals.Any())
             {
                 throw new ArgumentException("At least one signal must be provided");
             }
@@ -285,7 +285,7 @@ public WaveFile(IList<DiscreteSignal> signals, short bitsPerSample = 16)
         }
 
         /// <summary>
-        /// Construct WAV container by loading into it one <paramref name="signal"/> with given <paramref name="bitsPerSample"/>.
+        /// Constructs WAV container by loading into it one <paramref name="signal"/> with given <paramref name="bitsPerSample"/>.
         /// </summary>
         /// <param name="signal">Signal to be loaded into container</param>
         /// <param name="bitsPerSample">Bit depth</param>
@@ -294,7 +294,7 @@ public WaveFile(DiscreteSignal signal, short bitsPerSample = 16) : this(new [] {
         }
 
         /// <summary>
-        /// Return the contents of PCM WAV container as array of bytes.
+        /// Returns the contents of PCM WAV container as array of bytes.
         /// </summary>
         /// <param name="normalized">True if samples are normalized</param>
         public byte[] GetBytes(bool normalized = true)
@@ -307,7 +307,7 @@ public byte[] GetBytes(bool normalized = true)
         }
 
         /// <summary>
-        /// Save the contents of PCM WAV container to <paramref name="waveStream"/>.
+        /// Saves the contents of PCM WAV container to <paramref name="waveStream"/>.
         /// </summary>
         /// <param name="waveStream">Output stream</param>
         /// <param name="normalized">True if samples are normalized</param>
@@ -400,7 +400,7 @@ public void SaveTo(Stream waveStream, bool normalized = true)
         }
 
         /// <summary>
-        /// <para>Return container's signal using indexing based on channel type. Examples</para>
+        /// <para>Gets the signal from container using indexing scheme based on channel type. Examples</para>
         /// <code>
         ///     waveFile[Channels.Left]  -> waveFile.Signals[0]
         ///     <br/>

NWaves/Operations/DynamicsMode.cs

@@ -1,24 +1,27 @@
 namespace NWaves.Operations
 {
+    /// <summary>
+    /// Types (modes) of dynamics processors.
+    /// </summary>
     public enum DynamicsMode
     {
         /// <summary>
-        /// Smaller ratios, like 1:1, 2:1
+        /// Smaller ratios, like 1:1, 2:1.
         /// </summary>
         Compressor,
 
         /// <summary>
-        /// Bigger ratios, like 5:1, 10:1
+        /// Bigger ratios, like 5:1, 10:1.
         /// </summary>
         Limiter,
 
         /// <summary>
-        /// Smaller ratios, like 1:1, 2:1
+        /// Smaller ratios, like 1:1, 2:1.
         /// </summary>
         Expander,
 
         /// <summary>
-        /// Very high ratios, like 5:1
+        /// Very high ratios, like 5:1.
         /// </summary>
         NoiseGate
     }