Add public documentation

Author: xoofx

src/NPlug.CodeGen/CodeGenerator.cs

@@ -121,7 +121,13 @@ public void Generate(string destinationFolder)
 
         // Prepare for the C# generated file
         var csFile = new CSharpGeneratedFile("/LibVst.generated.cs");
-        csFile.Members.Add(new CSharpFreeMember() { Text = "#pragma warning disable CS0649" });
+        csFile.Members.Add(new CSharpFreeMember() { Text = @"#pragma warning disable CS0649
+#pragma warning disable CS1658
+#pragma warning disable CS1570
+#pragma warning disable CS1573
+#pragma warning disable CS1574
+#pragma warning disable CS1584
+" });
         csFile.Members.Add(new CSharpNamespace("NPlug.Interop") { IsFileScoped = true });
         csFile.Members.Add(new CSharpUsingDeclaration("System.Collections.Generic"));
         csFile.Members.Add(new CSharpUsingDeclaration("System.Diagnostics.CodeAnalysis"));

src/NPlug/AudioAttributeList.cs

@@ -8,135 +8,274 @@
 
 namespace NPlug;
 
+/// <summary>
+/// A list of attribute used to communicate with the host (e.g via message).
+/// </summary>
 public readonly ref struct AudioAttributeList
 {
     private readonly IAudioAttributeListBackend? _backend;
     internal readonly IntPtr NativeContext;
+
+    /// <summary>
+    /// Creates a new instance.
+    /// </summary>
     public AudioAttributeList(IAudioAttributeListBackend? backend, IntPtr nativeContext)
     {
         _backend = backend;
         NativeContext = nativeContext;
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetBool(string attributeId, bool value)
     {
         return TrySetInt64(attributeId, value ? 1 : 0);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetBool(string attributeId, out bool value)
     {
         var result = TryGetInt64(attributeId, out var intValue);
         value = intValue != 0;
         return result;
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetByte(string attributeId, byte value)
     {
         return TrySetInt64(attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetByte(string attributeId, out byte value)
     {
         var result = TryGetInt64(attributeId, out var intValue);
         value = (byte)intValue;
         return result;
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetInt16(string attributeId, short value)
     {
         return TrySetInt64(attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetInt16(string attributeId, out short value)
     {
         var result = TryGetInt64(attributeId, out var intValue);
         value = (short)intValue;
         return result;
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetUInt16(string attributeId, ushort value)
     {
         return TrySetInt64(attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetUInt16(string attributeId, out ushort value)
     {
         var result = TryGetInt64(attributeId, out var intValue);
         value = (ushort)intValue;
         return result;
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetUInt32(string attributeId, uint value)
     {
         return TrySetInt64(attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetUInt32(string attributeId, out uint value)
     {
         var result = TryGetInt64(attributeId, out var intValue);
         value = unchecked((uint)intValue);
         return result;
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetInt32(string attributeId, int value)
     {
         return TrySetInt64(attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetInt32(string attributeId, out int value)
     {
         var result = TryGetInt64(attributeId, out var intValue);
         value = unchecked((int)intValue);
         return result;
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetFloat32(string attributeId, float value)
     {
         return TrySetFloat64(attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetFloat32(string attributeId, out float value)
     {
         var result = TryGetFloat64(attributeId, out var doubleValue);
         value = (float)doubleValue;
         return result;
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetInt64(string attributeId, long value)
     {
         return GetSafeBackend().TrySetInt64(this, attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetInt64(string attributeId, out long value)
     {
         return GetSafeBackend().TryGetInt64(this, attributeId, out value);
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetFloat64(string attributeId, double value)
     {
         return GetSafeBackend().TrySetFloat64(this, attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetFloat64(string attributeId, out double value)
     {
         return GetSafeBackend().TryGetFloat64(this, attributeId, out value);
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetString(string attributeId, string value)
     {
         return GetSafeBackend().TrySetString(this, attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     public bool TryGetString(string attributeId, out string value)
     {
         return GetSafeBackend().TryGetString(this, attributeId, out value);
     }
 
+    /// <summary>
+    /// Tries to set a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to set.</param>
+    /// <returns><c>true</c> if the value was successfully set; <c>false</c> otherwise</returns>
     public bool TrySetBinary(string attributeId, ReadOnlySpan<byte> value)
     {
         return GetSafeBackend().TrySetBinary(this, attributeId, value);
     }
 
+    /// <summary>
+    /// Tries to get a value for the specified attribute.
+    /// </summary>
+    /// <param name="attributeId">The name of the attribute.</param>
+    /// <param name="value">The value to get.</param>
+    /// <returns><c>true</c> if the value was successfully get; <c>false</c> otherwise</returns>
     [UnscopedRef]
     public bool TryGetBinary(string attributeId, out ReadOnlySpan<byte> value)
     {

src/NPlug/AudioBoolParameter.cs

@@ -4,17 +4,29 @@
 
 namespace NPlug;
 
+/// <summary>
+/// A boolean <see cref="AudioParameter"/> that maps <c>true</c> to 1.0 and false to 0.0.
+/// </summary>
 public class AudioBoolParameter : AudioParameter
 {
+    /// <summary>
+    /// Creates a new instance of this parameter.
+    /// </summary>
     public AudioBoolParameter(AudioParameterInfo info) : base(info)
     {
         StepCount = 1;
     }
 
+    /// <summary>
+    /// Creates a new instance of this parameter.
+    /// </summary>
     public AudioBoolParameter(string title, int id = 0, string? units = null, string? shortTitle = null, bool defaultValue = false, AudioParameterFlags flags = AudioParameterFlags.CanAutomate) : base(title, units, id, shortTitle, 1, defaultValue ? 1.0 : 0.0, flags)
     {
     }
 
+    /// <summary>
+    /// Gets or sets the value of this parameter.
+    /// </summary>
     public bool Value
     {
         get

src/NPlug/AudioBusBuffers.cs

@@ -7,6 +7,9 @@
 
 namespace NPlug;
 
+/// <summary>
+/// The buffers for a specific bus, used in <see cref="AudioBusData"/> while processing audio via <see cref="IAudioProcessor.Process"/>.
+/// </summary>
 public unsafe ref struct AudioBusBuffers
 {
     /// <summary>
@@ -19,9 +22,14 @@ public unsafe ref struct AudioBusBuffers
     /// </summary>
     public ulong SilenceFlags;
 
+    // internal pointer to buffers. Use GetChannelSpanAsBytes / GetChannelSpanAsFloat32 / GetChannelSpanAsFloat64 methods.
     private readonly void** _channelBuffers;
-
-
+    
+    /// <summary>
+    /// Mark a specific channel as silence or not.
+    /// </summary>
+    /// <param name="channelIndex">The index of the channel.</param>
+    /// <param name="silence"><c>true</c> to mark the channel as silence.</param>
     public void SetChannelSilence(int channelIndex, bool silence)
     {
         if (silence)
@@ -34,22 +42,51 @@ public void SetChannelSilence(int channelIndex, bool silence)
         }
     }
 
+    /// <summary>
+    /// Checks whether the specified channel is silenced.
+    /// </summary>
+    /// <param name="channelIndex">The index of the channel.</param>
+    /// <returns><c>true</c> if the channel is silenced.</returns>
     public bool IsChannelSilence(int channelIndex) => (SilenceFlags & (1UL << channelIndex)) != 0;
 
+    /// <summary>
+    /// Safely gets the buffer associated with the current sampling rate and sample size.
+    /// </summary>
+    /// <param name="setupData">The processing setup data initialized by <see cref="IAudioProcessor.SetupProcessing"/>.</param>
+    /// <param name="processData">The processing data provided during <see cref="IAudioProcessor.Process"/>.</param>
+    /// <param name="channelIndex">The index of the channel.</param>
+    /// <returns>A span of the audio buffer.</returns>
+    /// <exception cref="ArgumentException">If the index is out of range.</exception>
     public Span<byte> GetChannelSpanAsBytes(in AudioProcessSetupData setupData, in AudioProcessData processData, int channelIndex)
     {
         if ((uint)channelIndex >= (uint)ChannelCount) throw new ArgumentException($"Invalid Channel Index {channelIndex}", nameof(channelIndex));
         var size = setupData.SampleSize == AudioSampleSize.Float32 ? 4 : 8;
         return new Span<byte>((byte*)_channelBuffers[channelIndex], size * processData.SampleCount);
     }
 
+    /// <summary>
+    /// Safely gets the buffer associated with the current sampling rate and sample size.
+    /// </summary>
+    /// <param name="setupData">The processing setup data initialized by <see cref="IAudioProcessor.SetupProcessing"/>.</param>
+    /// <param name="processData">The processing data provided during <see cref="IAudioProcessor.Process"/>.</param>
+    /// <param name="channelIndex">The index of the channel.</param>
+    /// <returns>A span of the audio buffer.</returns>
+    /// <exception cref="ArgumentException">If the index is out of range or the sample size is not Float32.</exception>
     public Span<float> GetChannelSpanAsFloat32(in AudioProcessSetupData setupData, in AudioProcessData processData, int channelIndex)
     {
         if (setupData.SampleSize != AudioSampleSize.Float32) throw new InvalidOperationException($"Expecting 32-bit samples but getting {setupData.SampleSize}");
         if ((uint)channelIndex >= (uint)ChannelCount) throw new ArgumentException($"Invalid Channel Index {channelIndex}", nameof(channelIndex));
         return new Span<float>((float*)_channelBuffers[channelIndex], processData.SampleCount);
     }
 
+    /// <summary>
+    /// Safely gets the buffer associated with the current sampling rate and sample size.
+    /// </summary>
+    /// <param name="setupData">The processing setup data initialized by <see cref="IAudioProcessor.SetupProcessing"/>.</param>
+    /// <param name="processData">The processing data provided during <see cref="IAudioProcessor.Process"/>.</param>
+    /// <param name="channelIndex">The index of the channel.</param>
+    /// <returns>A span of the audio buffer.</returns>
+    /// <exception cref="ArgumentException">If the index is out of range or the sample size is not Float64.</exception>
     public Span<double> GetChannelSpanAsFloat64(in AudioProcessSetupData setupData, in AudioProcessData processData, int channelIndex)
     {
         if (setupData.SampleSize != AudioSampleSize.Float64) throw new InvalidOperationException($"Expecting 64-bit samples but getting {setupData.SampleSize}");