Add XML docs and reduce warnings.

.github/workflows/develop-ci.yml

@@ -30,7 +30,6 @@ jobs:
       uses: actions/checkout@v3
       with:
         path: Meadow.Contracts
-        ref: develop
 
     - name: Setup .NET SDK
       uses: actions/setup-dotnet@v1

.github/workflows/main-ci.yml

@@ -17,7 +17,6 @@ jobs:
       uses: actions/checkout@v3
       with:
         path: Meadow.Contracts
-        ref: main
 
     - name: Setup .NET
       uses: actions/setup-dotnet@v1

Source/Meadow.Contracts/ExtensionMethods.cs

@@ -4,21 +4,31 @@
 
 namespace Meadow;
 
+/// <summary>
+/// ExtensionMethods class
+/// </summary>
 public static class ExtensionMethods
 {
     /// <summary>
-    /// 
+    /// Contains static extention method to check if the pattern exists within the source
     /// </summary>
     /// <typeparam name="TSource"></typeparam>
     /// <param name="source"></param>
     /// <param name="pattern"></param>
-    /// <returns></returns>
+    /// <returns>true if the pattern exists</returns>
     // TODO: move this into the `CircularBuffer` class? or is it broadly applicable?
     public static bool Contains<TSource>(this IEnumerable<TSource> source, TSource[] pattern)
     {
         return (source.FirstIndexOf(pattern) != -1);
     }
 
+    /// <summary>
+    /// FirstIndexOf static extention method for an IEnumerable
+    /// </summary>
+    /// <typeparam name="TSource"></typeparam>
+    /// <param name="source"></param>
+    /// <param name="pattern"></param>
+    /// <returns>the index position of the found pattern</returns>
     // TODO: move this into the `CircularBuffer` class? or is it broadly applicable?
     public static int FirstIndexOf<TSource>(this IEnumerable<TSource> source, TSource[] pattern)
     {
@@ -106,51 +116,63 @@ public static int Map(this int sourceValue, int sourceMin, int sourceMax, int ta
         return (sourceValue - sourceMin) / (sourceMax - sourceMin) * (targetMax - targetMin) + targetMin;
     }
 
+    /// <summary>
+    /// Traverses the handler's invocation list and invokes each via the EventHandler() method
+    /// </summary>
+    /// <param name="handler">The delegate we are acting upon.</param>
+    /// <param name="args">The arguments we want to pass to each delegate.</param>
     public static void Fire(this Delegate handler, params object[] args)
     {
-        if (handler == null) return;
-        foreach (var d in handler.GetInvocationList())
-        {
-            try
-            {
-                d.DynamicInvoke(args);
-            }
-            catch (Exception ex)
-            {
-                Resolver.Log.Error($"Event handler threw {ex.GetType().Name}: {ex.Message}");
-            }
-        }
+        EventHandler(handler, args);
     }
 
-    public static void Fire(this EventHandler h, object sender)
+    /// <summary>
+    /// Traverses the handler's invocation list and invokes each via the EventHandler() method
+    /// </summary>
+    /// <param name="handler">The eventhandler we are acting upon.</param>
+    /// <param name="sender">The sender object.</param>
+    public static void Fire(this EventHandler handler, object sender)
     {
-        Fire(h, sender, EventArgs.Empty);
+        EventHandler(handler, sender, EventArgs.Empty);
     }
 
+    /// <summary>
+    /// Traverses the handler's invocation list and invokes each via the EventHandler() method
+    /// </summary>
+    /// <param name="handler">The eventhandler we are acting upon.</param>
+    /// <param name="sender">The sender object.</param>
+    /// <param name="args">The arguments we want to pass to each delegate.</param>
     public static void Fire(this EventHandler handler, object sender, EventArgs args)
     {
-        if (handler == null) return;
-        foreach (var d in handler.GetInvocationList())
-        {
-            try
-            {
-                d.DynamicInvoke(sender, args);
-            }
-            catch (Exception ex)
-            {
-                Resolver.Log.Error($"Event handler threw {ex.GetType().Name}: {ex.Message}");
-            }
-        }
+        EventHandler(handler, sender, args);
     }
 
+    /// <summary>
+    /// Traverses the handler's invocation list and invokes each via the EventHandler() method
+    /// </summary>
+    /// <param name="handler">The eventhandler we are acting upon.</param>
+    /// <param name="sender">The sender object.</param>
+    /// <param name="args">The arguments we want to pass to each delegate.</param>
     public static void Fire<T>(this EventHandler<T> handler, object sender, T args) where T : EventArgs
     {
-        if (handler == null) return;
+        EventHandler(handler, sender, args);
+    }
+
+    /// <summary>
+    /// Centralised EventHandler that traverses the handler's invocation list and invokes each with the args
+    /// </summary>
+    /// <param name="handler">The delegate we are acting upon.</param>
+    /// <param name="args">The arguments we want to pass to each delegate.</param>
+    private static void EventHandler(Delegate handler, params object[] args)
+    {
+        if (handler == null)
+            return;
+
         foreach (var d in handler.GetInvocationList())
         {
             try
             {
-                d.DynamicInvoke(sender, args);
+                d.DynamicInvoke(args);
             }
             catch (Exception ex)
             {

Source/Meadow.Contracts/Hardware/Contracts/IPinDefinitions.cs

@@ -28,6 +28,6 @@ IPin this[string name]
         /// <summary>
         /// Gets or sets the IPinController associated with the IPins
         /// </summary>
-        IPinController Controller { get; set; }
+        IPinController? Controller { get; set; }
     }
 }

Source/Meadow.Contracts/Hardware/NamedPinGroup.cs

@@ -1,9 +1,18 @@
 namespace Meadow.Hardware
 {
+    /// <summary>
+    /// NamedPinGroup class
+    /// </summary>
     public class NamedPinGroup
     {
+        /// <summary>
+        /// The name property of the <see cref="NamedPinGroup"/> class.
+        /// </summary>
         public string Name { get; protected set; }
 
+        /// <summary>
+        /// The Pins array property of the <see cref="NamedPinGroup"/> class.
+        /// </summary>
         public IPin[] Pins { get; protected set; }
 
         /// <summary>
@@ -23,6 +32,9 @@ public NamedPinGroup(string name, IPin[] pins)
         /// <returns>The Name of the <see cref="NamedPinGroup"/> object.</returns>
         public override string ToString() => Name;
 
+        /// <summary>
+        /// => operator overload for the IPin[] array.
+        /// </summary>
         public static implicit operator IPin[](NamedPinGroup namedPinGroup) => namedPinGroup.Pins;
     }
 }

Source/Meadow.Contracts/Hardware/PinDefinitionBase.cs

@@ -14,10 +14,9 @@ public abstract class PinDefinitionBase : IPinDefinitions
     public IList<IPin> AllPins => _pins;
 
     /// <inheritdoc/>
-    public IPinController Controller { get; set; }
+    public IPinController? Controller { get; set; }
 
     /// <inheritdoc/>
     public IEnumerator<IPin> GetEnumerator() => _pins.GetEnumerator();
     IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
-}
-
+}

Source/Meadow.Contracts/Hardware/SerialPortName.cs

@@ -5,13 +5,21 @@
     /// </summary>
     public class SerialPortName
     {
+        /// <summary>
+        /// The SerialController in documentation
+        /// </summary>
         public ISerialController? SerialController { get; private set; }
+
+        /// <summary>
+        /// The SerialMessageController in documentation
+        /// </summary>
         public ISerialMessageController? SerialMessageController { get; private set; }
 
         /// <summary>
         /// The common name used for the port in documentation
         /// </summary>
         public string FriendlyName { get; set; }
+
         /// <summary>
         /// The assigned driver name for the port
         /// </summary>

Source/Meadow.Contracts/Platform OS/IPlatformOS.Storage.cs

@@ -24,17 +24,28 @@ public enum ExternalStorageState
         /// </summary>
         Ejected
     }
+
     /// <summary>
     /// Contract for external storage devices.
     /// </summary>
     public interface IExternalStorage
     {
+        /// <summary>
+        /// Directory information property
+        /// </summary>
         public DirectoryInfo Directory { get; } // this or string???
+
+        /// <summary>
+        /// Eject Storage Device method
+        /// </summary>
         public void Eject();
     }
 
     public partial interface IPlatformOS
     {
+        /// <summary>
+        /// FileSystemInfo property
+        /// </summary>
         public abstract FileSystemInfo FileSystem { get; }
 
         /// <summary>