Merge pull request #139 from martincostello/Add-XML-Documentation

XML documentation updates

src/JustEat.StatsD.Tests/Extensions/ExtensionsTests.cs

@@ -1,4 +1,4 @@
-using System.Threading;
+using System.Threading;
 using System.Threading.Tasks;
 using Shouldly;
 using Xunit;
@@ -131,7 +131,7 @@ public static void CanChangeStatNameInAction()
         public static void CanRecordStatInFunction()
         {
             var publisher = new FakeStatsPublisher();
-            var answer = publisher.Time("statOverFunc", t => DelayedAnswer());
+            var answer = publisher.Time("statOverFunc", () => DelayedAnswer());
 
             answer.ShouldBe(42);
             PublisherAssertions.SingleStatNameIs(publisher, "statOverFunc");
@@ -142,7 +142,7 @@ public static void CanRecordStatInFunction()
         public static async Task CanRecordStatInAsyncAction()
         {
             var publisher = new FakeStatsPublisher();
-            await publisher.Time("statOverAsyncAction", async t => await DelayAsync());
+            await publisher.Time("statOverAsyncAction", async () => await DelayAsync());
 
             PublisherAssertions.SingleStatNameIs(publisher, "statOverAsyncAction");
         }
@@ -151,7 +151,7 @@ public static async Task CanRecordStatInAsyncAction()
         public static async Task CorrectDurationForStatInAsyncAction()
         {
             var publisher = new FakeStatsPublisher();
-            await publisher.Time("stat", async t => await DelayAsync());
+            await publisher.Time("stat", async () => await DelayAsync());
 
             PublisherAssertions.LastDurationIs(publisher, TimingConstants.DelayMilliseconds);
         }
@@ -160,7 +160,7 @@ public static async Task CorrectDurationForStatInAsyncAction()
         public static async Task CanRecordStatInAsyncFunction()
         {
             var publisher = new FakeStatsPublisher();
-            var answer = await publisher.Time("statOverAsyncFunc", async t => await DelayedAnswerAsync());
+            var answer = await publisher.Time("statOverAsyncFunc", async () => await DelayedAnswerAsync());
 
             answer.ShouldBe(42);
             PublisherAssertions.SingleStatNameIs(publisher, "statOverAsyncFunc");
@@ -170,7 +170,7 @@ public static async Task CanRecordStatInAsyncFunction()
         public static async Task CorrectDurationForStatInAsyncFunction()
         {
             var publisher = new FakeStatsPublisher();
-            await publisher.Time("stat", async t => await DelayedAnswerAsync());
+            await publisher.Time("stat", async () => await DelayedAnswerAsync());
 
             PublisherAssertions.LastDurationIs(publisher, TimingConstants.DelayMilliseconds);
         }

src/JustEat.StatsD/EndpointLookups/CachedEndpointSource.cs

@@ -4,23 +4,32 @@
 namespace JustEat.StatsD.EndpointLookups
 {
     /// <summary>
-    /// cache the IPEndPoint and only go to the source when it expires
+    /// A class representing an implementation of <see cref="IEndPointSource"/> that caches
+    /// the <see cref="EndPoint"/> for a fixed period of time before refreshing its value.
     /// </summary>
     public class CachedEndpointSource : IEndPointSource
     {
+        private readonly IEndPointSource _inner;
+        private readonly TimeSpan _cacheDuration;
         private EndPoint _cachedValue;
         private DateTime _expiry;
-        private readonly TimeSpan _cacheDuration;
-
-        private readonly IEndPointSource _inner;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CachedEndpointSource"/> class.
+        /// </summary>
+        /// <param name="inner">The inner <see cref="IEndPointSource"/> to use.</param>
+        /// <param name="cacheDuration">The duration values should be cached for.</param>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="inner"/> is <see langword="null"/>.
+        /// </exception>
         public CachedEndpointSource(IEndPointSource inner, TimeSpan cacheDuration)
         {
-            _inner = inner;
+            _inner = inner ?? throw new ArgumentNullException(nameof(inner));
             _cachedValue = null;
             _cacheDuration = cacheDuration;
         }
 
+        /// <inheritdoc />
         public EndPoint GetEndpoint()
         {
             if (NeedsRead())

src/JustEat.StatsD/EndpointLookups/DnsLookupIpEndpointSource.cs

@@ -6,22 +6,33 @@
 namespace JustEat.StatsD.EndpointLookups
 {
     /// <summary>
-    /// lookup IPAddress using DNS to find the host's IP
+    /// A class representing an implementation of <see cref="IEndPointSource"/> that looks up
+    /// the <see cref="EndPoint"/> for DNS hostname to resolve its IP address.
     /// </summary>
     public class DnsLookupIpEndpointSource : IEndPointSource
     {
         private readonly string _hostName;
         private readonly int _port;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DnsLookupIpEndpointSource"/> class.
+        /// </summary>
+        /// <param name="hostName">The host name to look up the IP address for.</param>
+        /// <param name="port">The port number to use for the end point.</param>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="hostName"/> is <see langword="null"/>.
+        /// </exception>
         public DnsLookupIpEndpointSource(string hostName, int port)
         {
-            _hostName = hostName;
+            _hostName = hostName ?? throw new ArgumentNullException(nameof(hostName));
             _port = port;
         }
 
+        /// <inheritdoc />
         public EndPoint GetEndpoint()
         {
-            return new IPEndPoint(GetIpAddressOfHost(_hostName), _port);
+            var address = GetIpAddressOfHost(_hostName);
+            return new IPEndPoint(address, _port);
         }
 
         private static IPAddress GetIpAddressOfHost(string hostName)
@@ -30,7 +41,7 @@ private static IPAddress GetIpAddressOfHost(string hostName)
 
             if (endpoints == null || endpoints.Length == 0)
             {
-                throw new Exception($"DNS did not find any addresses for statsd host '${hostName}'");
+                throw new Exception($"Failed to resolve any IP addresses for statsd host '${hostName}' using DNS.");
             }
 
             IPAddress result = null;

src/JustEat.StatsD/EndpointLookups/EndpointParser.cs

@@ -3,8 +3,24 @@
 
 namespace JustEat.StatsD.EndpointLookups
 {
+    //// TODO Is this more of a EndPointFactory?
+
+    /// <summary>
+    /// A class containing methods to instances of <see cref="IEndPointSource"/>. This class cannot be inherited.
+    /// </summary>
     public static class EndpointParser
     {
+        /// <summary>
+        /// Creates an <see cref="IEndPointSource"/> from the specified <see cref="EndPoint"/>.
+        /// </summary>
+        /// <param name="endpoint">The <see cref="EndPoint"/> to create the end point source for.</param>
+        /// <param name="endpointCacheDuration">The optional period of time to cache the end point value for.</param>
+        /// <returns>
+        /// The created instance of <see cref="IEndPointSource"/>.
+        /// </returns>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="endpoint"/> is <see langword="null"/>.
+        /// </exception>
         public static IEndPointSource MakeEndPointSource(EndPoint endpoint, TimeSpan? endpointCacheDuration)
         {
             if (endpoint == null)
@@ -14,38 +30,54 @@ public static IEndPointSource MakeEndPointSource(EndPoint endpoint, TimeSpan? en
 
             IEndPointSource source = new SimpleEndpointSource(endpoint);
 
-            if (!endpointCacheDuration.HasValue)
+            if (endpointCacheDuration.HasValue)
             {
-                return source;
+                source = new CachedEndpointSource(source, endpointCacheDuration.Value);
             }
 
-            return new CachedEndpointSource(source, endpointCacheDuration.Value);
+            return source;
         }
 
+        /// <summary>
+        /// Creates an <see cref="IEndPointSource"/> from the specified host IP address or name and port.
+        /// </summary>
+        /// <param name="host">The host name of IP address of the statsd server.</param>
+        /// <param name="port">The port number to use for the end point.</param>
+        /// <param name="endpointCacheDuration">The optional period of time to cache the end point value for.</param>
+        /// <returns>
+        /// The created instance of <see cref="IEndPointSource"/>.
+        /// </returns>
+        /// <exception cref="ArgumentException">
+        /// <paramref name="host"/> is either <see langword="null"/> or the empty string.
+        /// </exception>
         public static IEndPointSource MakeEndPointSource(string host, int port, TimeSpan? endpointCacheDuration)
         {
             if (string.IsNullOrWhiteSpace(host))
             {
-                throw new ArgumentException("statsd host is null or empty");
+                throw new ArgumentException("The statsd host IP address or name is null or empty.", nameof(host));
             }
 
+            IEndPointSource source;
+
             if (IPAddress.TryParse(host, out IPAddress address))
             {
                 // If we were given an IP instead of a hostname, 
                 // we can happily keep it the life of this class
-                var endpoint = new IPEndPoint(address, port);
-                return new SimpleEndpointSource(endpoint);
+                var value = new IPEndPoint(address, port);
+                source = new SimpleEndpointSource(value);
             }
-
-            // We have a host name, so we use DNS lookup
-            var uncachedLookup = new DnsLookupIpEndpointSource(host, port);
-
-            if (!endpointCacheDuration.HasValue)
+            else
             {
-                return uncachedLookup;
+                // We have a host name, so we use DNS lookup
+                source = new DnsLookupIpEndpointSource(host, port);
+
+                if (endpointCacheDuration.HasValue)
+                {
+                    source = new CachedEndpointSource(source, endpointCacheDuration.Value);
+                }
             }
 
-            return new CachedEndpointSource(uncachedLookup, endpointCacheDuration.Value);
+            return source;
         }
     }
 }

src/JustEat.StatsD/EndpointLookups/IEndPointSource.cs

@@ -2,8 +2,17 @@
 
 namespace JustEat.StatsD.EndpointLookups
 {
+    /// <summary>
+    /// Defines a method for retrieving the endpoint for a statsd server.
+    /// </summary>
     public interface IEndPointSource
     {
+        /// <summary>
+        /// Returns an <see cref="EndPoint"/> to use for a statsd server.
+        /// </summary>
+        /// <returns>
+        /// The <see cref="EndPoint"/> to use to publish metrics.
+        /// </returns>
         EndPoint GetEndpoint();
     }
 }

src/JustEat.StatsD/EndpointLookups/SimpleEndpointSource.cs

@@ -1,19 +1,29 @@
+using System;
 using System.Net;
 
 namespace JustEat.StatsD.EndpointLookups
 {
     /// <summary>
-    /// Simple adapter
+    /// A class representing an implementation of <see cref="IEndPointSource"/> that
+    /// returns a constant <see cref="EndPoint"/> value. This class cannot be inherited.
     /// </summary>
-    public class SimpleEndpointSource : IEndPointSource
+    public sealed class SimpleEndpointSource : IEndPointSource
     {
         private readonly EndPoint _value;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SimpleEndpointSource"/> class.
+        /// </summary>
+        /// <param name="value">The <see cref="EndPoint"/> to use.</param>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="value"/> is <see langword="null"/>.
+        /// </exception>
         public SimpleEndpointSource(EndPoint value)
         {
-            _value = value;
+            _value = value ?? throw new ArgumentNullException(nameof(value));
         }
 
+        /// <inheritdoc />
         public EndPoint GetEndpoint() => _value;
     }
 }

src/JustEat.StatsD/IDisposableTimer.cs

@@ -1,9 +1,15 @@
-using System;
+using System;
 
 namespace JustEat.StatsD
 {
+    /// <summary>
+    /// Defines a timer which is disposable.
+    /// </summary>
     public interface IDisposableTimer : IDisposable
     {
+        /// <summary>
+        /// Gets or sets the name of the statsd bucket associated with the timer.
+        /// </summary>
         string StatName { get; set; }
     }
 }

src/JustEat.StatsD/IStatsDPublisher.cs

@@ -17,7 +17,6 @@ public interface IStatsDPublisher
         /// Publishes a gauge for the specified bucket and value.
         /// </summary>
         /// <param name="value">The value to publish for the gauge.</param>
-        /// <param name="sampleRate">The sample rate for the gauge.</param>
         /// <param name="bucket">The bucket to publish the gauge for.</param>
         void Gauge(double value, string bucket);