Enable generation of SIPSorcery.xml documentation file (#1106)

* Enabled GenerateDocumentationFile in SIPSorcery.csproj
* Disabled "missing XML comment" warnings
* Fixed most malformed XML comments (warnings about these are not disabled)

src/SIPSorcery.csproj

@@ -28,6 +28,9 @@
     <TargetFrameworks>netstandard2.0;netstandard2.1;netcoreapp3.1;net461;net5.0;net6.0;net8.0</TargetFrameworks>
     <SuppressTfmSupportBuildWarnings>true</SuppressTfmSupportBuildWarnings>
     <NoWarn>$(NoWarn);SYSLIB0050</NoWarn>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <!-- Disable warning for missing XML doc comments. -->
+    <NoWarn>$(NoWarn);CS1591;CS1573;CS1587</NoWarn>
     <Authors>Aaron Clauson, Christophe Irles, Rafael Soares &amp; Contributors</Authors>
     <Copyright>Copyright © 2010-2024 Aaron Clauson</Copyright>
     <PackageLicenseExpression>BSD-3-Clause</PackageLicenseExpression>

src/app/Media/Codecs/AudioEncoder.cs

@@ -123,9 +123,8 @@ public byte[] EncodeAudio(short[] pcm, AudioFormat format)
         /// <summary>
         /// Event handler for receiving RTP packets from the remote party.
         /// </summary>
-        /// <param name="remoteEP">The remote end point the RTP was received from.</param>
+        /// <param name="encodedSample">Data received from an RTP socket.</param>
         /// <param name="format">The audio format of the encoded packets.</param>
-        /// <param name="rtpPacket">The RTP packet with the media sample.</param>
         public short[] DecodeAudio(byte[] encodedSample, AudioFormat format)
         {
             if (format.Codec == AudioCodecsEnum.G722)

src/app/Media/Codecs/G729Codec/CodLd8k.cs

@@ -155,7 +155,7 @@ COPYRIGHT NOTICE
         /**
  * Initialization of variables for the encoder.
  * Initialize pointers to speech vector.
- *<pre>
+ *<pre> <![CDATA[
  *   |--------------------|-------------|-------------|------------|
  *     previous speech           sf1           sf2         L_NEXT
  *
@@ -166,7 +166,7 @@ COPYRIGHT NOTICE
  *     p_wind            |              |
  *                     speech           |
  *                             new_speech
- * </pre>
+ * ]]></pre>
  */
 
         public void init_coder_ld8k()
@@ -543,4 +543,4 @@ int[] ana
             Util.copy(old_exc, L_FRAME, old_exc, PIT_MAX + L_INTERPOL);
         }
     }
-}
+}

src/app/Media/Codecs/G729Codec/CorFunc.cs

@@ -59,7 +59,7 @@ COPYRIGHT NOTICE
  * @param xn        input : target vector x[0:l_subfr]
  * @param y1        input : filtered adaptive codebook vector
  * @param y2        input : filtered 1st codebook innovation
- * @param g_coeff   output: <y2,y2> , -2<xn,y2> , and 2<y1,y2>
+ * @param g_coeff   <![CDATA[ output: <y2,y2> , -2<xn,y2> , and 2<y1,y2> ]]>
  */
 
         public static void corr_xy2(
@@ -115,4 +115,4 @@ float[] d
             }
         }
     }
-}
+}

src/app/Media/Codecs/G729Codec/Gainpred.cs

@@ -118,13 +118,13 @@ float g_code
 
         /**
  * Update table of past quantized energies (frame erasure).
- * <pre>
+ * <pre> <![CDATA[
  *     av_pred_en = 0.0;
  *     for (i = 0; i < 4; i++)
  *        av_pred_en += past_qua_en[i];
  *     av_pred_en = av_pred_en*0.25 - 4.0;
  *     if (av_pred_en < -14.0) av_pred_en = -14.0;
- * </pre>
+ * ]]></pre>
  *
  * @param past_qua_en   input/output:Past quantized energies
  */
@@ -147,4 +147,4 @@ float[] past_qua_en
             past_qua_en[0] = av_pred_en;
         }
     }
-}
+}

src/app/Media/Codecs/G729Codec/Ld8k.cs

@@ -124,12 +124,12 @@ public class Ld8k
         public static float GAMMA2_PST = 0.55f;
 
         /**
- * tilt weighting factor when k1<0
+ * tilt weighting factor when k1 &lt; 0
  */
         public static float GAMMA3_MINUS = 0.9f;
 
         /**
- * tilt weighting factor when k1>0
+ * tilt weighting factor when k1 &gt; 0
  */
         public static float GAMMA3_PLUS = 0.2f;
 
@@ -479,4 +479,4 @@ COPYRIGHT NOTICE
  * resolution of fractional delays
  */
     }
-}
+}

src/app/Media/Codecs/G729Codec/Pitch.cs

@@ -351,14 +351,15 @@ int corr_norm_offset
             }
         }
 
-        /**
+        /** <![CDATA[
  * Compute adaptive codebook gain and compute <y1,y1> , -2<xn,y1>
  *
  * @param xn        input : target vector
  * @param y1        input : filtered adaptive codebook vector
  * @param g_coeff   output: <y1,y1> and -2<xn,y1>
  * @param l_subfr   input : vector dimension
  * @return          pitch gain
+ * ]]>
  */
 
         public static float g_pitch(
@@ -528,4 +529,4 @@ float x
             return 1.0f / (float)Math.Sqrt(x);
         }
     }
-}
+}

src/app/Media/Codecs/G729Codec/Postfil.cs

@@ -635,7 +635,7 @@ float gain_plt
 
         /**
  * Compute delayed signal,
- * num & den of gain for fractional delay
+ * num & den of gain for fractional delay
  * with long interpolation filter
  *
  * @param s_in           input signal with past
@@ -906,4 +906,4 @@ float gain_prec
             return gain_prec;
         }
     }
-}
+}

src/app/Media/IMediaSession.cs

@@ -102,7 +102,7 @@ public interface IMediaSession
         /// if they are.
         /// </summary>
         /// <param name="sdpType">Whether the SDP being set is an offer or answer.</param>
-        /// <param name="sdp">The SDP description from the remote party.</param>
+        /// <param name="sessionDescription">The SDP description from the remote party.</param>
         /// <returns>If successful an OK enum result. If not an enum result indicating the 
         /// failure cause.</returns>
         SetDescriptionResultEnum SetRemoteDescription(SdpType sdpType, SDP sessionDescription);
@@ -150,4 +150,4 @@ public interface IMediaSession
         /// <param name="reason">Optional. A descriptive reason for closing the session.</param>
         void Close(string reason);
     }
-}
+}

src/app/Media/Sources/AudioSignalGenerator.cs

@@ -67,7 +67,7 @@ public SignalGenerator()
         /// Initializes a new instance for the Generator (UserDef SampleRate & Channels)
         /// </summary>
         /// <param name="sampleRate">Desired sample rate</param>
-        /// <param name="channel">Number of channels</param>
+        /// <param name="channels">Number of channels</param>
         public SignalGenerator(int sampleRate, int channels)
         {
             phi = 0;

src/app/SIPUserAgents/SIPCallDescriptor.cs

@@ -265,7 +265,7 @@ public SIPFromHeader GetFromHeader()
         /// </summary>
         /// <param name="fromDisplayName"></param>
         /// <param name="fromUsername"></param>
-        /// <param name="fromhost"></param>
+        /// <param name="fromHost"></param>
         public void SetGeneralFromHeaderFields(string fromDisplayName, string fromUsername, string fromHost)
         {
             if (!fromDisplayName.IsNullOrBlank() && FromDisplayName == null)

src/app/SIPUserAgents/SIPUserAgent.cs

@@ -416,7 +416,7 @@ public SIPUserAgent(SIPTransport transport, SIPEndPoint outboundProxy, bool isTr
 
         /// <summary>
         /// Attempts to place a new outgoing call AND waits for the call to be answered or fail.
-        /// Use <see cref="InitiateCallAsync(SIPCallDescriptor, IMediaSession)"/> to start a call without
+        /// Use <see cref="InitiateCallAsync(SIPCallDescriptor, IMediaSession, int)"/> to start a call without
         /// waiting for it to complete and monitor <see cref="ClientCallAnsweredHandler"/> and
         /// <see cref="ClientCallFailedHandler"/> to detect an answer or failure.
         /// </summary>
@@ -464,7 +464,7 @@ public Task<bool> Call(string dst, string username, string password, IMediaSessi
 
         /// <summary>
         /// Attempts to place a new outgoing call AND waits for the call to be answered or fail.
-        /// Use <see cref="InitiateCallAsync(SIPCallDescriptor, IMediaSession)"/> to start a call without
+        /// Use <see cref="InitiateCallAsync(SIPCallDescriptor, IMediaSession, int)"/> to start a call without
         /// waiting for it to complete and monitor <see cref="ClientCallAnsweredHandler"/> and
         /// <see cref="ClientCallFailedHandler"/> to detect an answer or failure.
         /// </summary>

src/net/DtlsSrtp/Transform/SrtcpTransformer.cs

@@ -15,58 +15,58 @@
 // License:
 // BSD 3-Clause "New" or "Revised" License, see included LICENSE.md file.
 // Original Source: AGPL-3.0 License
-//-----------------------------------------------------------------------------
-
+//-----------------------------------------------------------------------------
+
 using System.Collections.Concurrent;
-using System.Collections.Generic;
+using System.Collections.Generic;
 using System.Threading;
 
-namespace SIPSorcery.Net
+namespace SIPSorcery.Net
 {
     /// <summary>
-    /// SRTCPTransformer implements PacketTransformer.
-    /// It encapsulate the encryption / decryption logic for SRTCP packets
-    ///
-    /// @author Bing SU (nova.su @gmail.com)
-    /// @author Werner Dittmann<Werner.Dittmann@t-online.de>
-    /// </summary>
-    public class SrtcpTransformer : IPacketTransformer
-    {
-        private int _isLocked = 0;
-        private RawPacket packet;
-
-        private SrtpTransformEngine forwardEngine;
-        private SrtpTransformEngine reverseEngine;
-
-        /** All the known SSRC's corresponding SRTCPCryptoContexts */
-        private ConcurrentDictionary<long, SrtcpCryptoContext> contexts;
-
-        public SrtcpTransformer(SrtpTransformEngine engine) : this(engine, engine)
-        {
-
-        }
-
-        public SrtcpTransformer(SrtpTransformEngine forwardEngine, SrtpTransformEngine reverseEngine)
-        {
-            this.packet = new RawPacket();
-            this.forwardEngine = forwardEngine;
-            this.reverseEngine = reverseEngine;
-            this.contexts = new ConcurrentDictionary<long, SrtcpCryptoContext>();
-        }
-
-        /// <summary>
-        /// Encrypts a SRTCP packet
+    /// SRTCPTransformer implements PacketTransformer.
+    /// It encapsulate the encryption / decryption logic for SRTCP packets
+    ///
+    /// @author Bing SU (nova.su @gmail.com)
+    /// @author Werner Dittmann (Werner.Dittmann@t-online.de)
+    /// </summary>
+    public class SrtcpTransformer : IPacketTransformer
+    {
+        private int _isLocked = 0;
+        private RawPacket packet;
+
+        private SrtpTransformEngine forwardEngine;
+        private SrtpTransformEngine reverseEngine;
+
+        /** All the known SSRC's corresponding SRTCPCryptoContexts */
+        private ConcurrentDictionary<long, SrtcpCryptoContext> contexts;
+
+        public SrtcpTransformer(SrtpTransformEngine engine) : this(engine, engine)
+        {
+
+        }
+
+        public SrtcpTransformer(SrtpTransformEngine forwardEngine, SrtpTransformEngine reverseEngine)
+        {
+            this.packet = new RawPacket();
+            this.forwardEngine = forwardEngine;
+            this.reverseEngine = reverseEngine;
+            this.contexts = new ConcurrentDictionary<long, SrtcpCryptoContext>();
+        }
+
+        /// <summary>
+        /// Encrypts a SRTCP packet
         /// </summary>
         /// <param name="pkt">plain SRTCP packet to be encrypted.</param>
         /// <returns>encrypted SRTCP packet.</returns>
-        public byte[] Transform(byte[] pkt)
-        {
-            return Transform(pkt, 0, pkt.Length);
-        }
-
-        public byte[] Transform(byte[] pkt, int offset, int length)
-        {
-            var isLocked = Interlocked.CompareExchange(ref _isLocked, 1, 0) != 0;
+        public byte[] Transform(byte[] pkt)
+        {
+            return Transform(pkt, 0, pkt.Length);
+        }
+
+        public byte[] Transform(byte[] pkt, int offset, int length)
+        {
+            var isLocked = Interlocked.CompareExchange(ref _isLocked, 1, 0) != 0;
             try
             {
                 // Wrap the data into raw packet for readable format
@@ -90,23 +90,23 @@ public byte[] Transform(byte[] pkt, int offset, int length)
                 byte[] result = packet.GetData();
 
                 return result;
-            }
-            finally
+            }
+            finally
             {
                 //Unlock
                 if (!isLocked)
                     Interlocked.CompareExchange(ref _isLocked, 0, 1);
-            }
-        }
-
-        public byte[] ReverseTransform(byte[] pkt)
-        {
-            return ReverseTransform(pkt, 0, pkt.Length);
-        }
-
-        public byte[] ReverseTransform(byte[] pkt, int offset, int length)
-        {
-            var isLocked = Interlocked.CompareExchange(ref _isLocked, 1, 0) != 0;
+            }
+        }
+
+        public byte[] ReverseTransform(byte[] pkt)
+        {
+            return ReverseTransform(pkt, 0, pkt.Length);
+        }
+
+        public byte[] ReverseTransform(byte[] pkt, int offset, int length)
+        {
+            var isLocked = Interlocked.CompareExchange(ref _isLocked, 1, 0) != 0;
             try
             {
                 // wrap data into raw packet for readable format
@@ -133,36 +133,36 @@ public byte[] ReverseTransform(byte[] pkt, int offset, int length)
                     result = packet.GetData();
                 }
                 return result;
-            }
-            finally
+            }
+            finally
             {
                 //Unlock
                 if (!isLocked)
                     Interlocked.CompareExchange(ref _isLocked, 0, 1);
-            }
-        }
-
+            }
+        }
+
         /// <summary>
         /// Close the transformer and underlying transform engine.
         /// The close functions closes all stored crypto contexts. This deletes key data
         /// and forces a cleanup of the crypto contexts.
-        /// </summary>
-        public void Close()
-        {
-            forwardEngine.Close();
+        /// </summary>
+        public void Close()
+        {
+            forwardEngine.Close();
             if (forwardEngine != reverseEngine)
             {
                 reverseEngine.Close();
-            }
-
-            var keys = new List<long>(contexts.Keys);
-            foreach (var ssrc in keys)
+            }
+
+            var keys = new List<long>(contexts.Keys);
+            foreach (var ssrc in keys)
             {
                 if (contexts.TryRemove(ssrc, out var context))
                 {
                     context.Close();
-                }
-            }
-        }
-    }
-}
+                }
+            }
+        }
+    }
+}