Ensured that Intellisense (XML-Doc) comments are present on all publi…

…c items.

TA.Utils.Core/AsciiExtensions.cs

@@ -1,29 +1,26 @@
-// This file is part of the TA.NexDome.AscomServer project
-// Copyright © 2019-2019 Tigra Astronomy, all rights reserved.
+// This file is part of the TA.Utils project
+// Copyright © 2016-2020 Tigra Astronomy, all rights reserved.
+// File: AsciiExtensions.cs  Last modified: 2020-07-13@02:11 by Tim Long
 
 using System;
 using System.Diagnostics.Contracts;
 using System.Text;
 
 namespace TA.Utils.Core
     {
+    /// <summary>Helper methods for manipulating strings of ASCII-encoded text.</summary>
     public static class AsciiExtensions
         {
-        /// <summary>
-        ///     Utility function. Expands non-printable ASCII characters into mnemonic human-readable
-        ///     form.
-        /// </summary>
-        /// <returns>
-        ///     Returns a new string with non-printing characters replaced by human-readable mnemonics.
-        /// </returns>
+        /// <summary>Expands non-printable ASCII characters into mnemonic human-readable form.</summary>
+        /// <returns>Returns a new string with non-printing characters replaced by human-readable mnemonics.</returns>
         public static string ExpandAscii(this string text)
             {
             Contract.Requires(text != null);
             Contract.Ensures(Contract.Result<string>() != null);
             var expanded = new StringBuilder();
             foreach (char c in text)
                 {
-                byte b = (byte)c;
+                byte b = (byte) c;
                 string strAscii = Enum.GetName(typeof(AsciiSymbols), b);
                 if (strAscii != null)
                     expanded.Append("<" + strAscii + ">");
@@ -34,6 +31,12 @@ public static string ExpandAscii(this string text)
             return expanded.ToString();
             }
 
+        /// <summary>
+        ///     Expands a non-printable ASCII character into mnemonic human-readable form. If the character is
+        ///     printable, then the character is returned as a string.
+        /// </summary>
+        /// <returns>Returns a new string with non-printing characters replaced by human-readable mnemonics.</returns>
+        /// <remarks>To convert a whole string on one go, use the overload that accepts a string.</remarks>
         public static string ExpandAscii(this char c)
             {
             Contract.Ensures(Contract.Result<string>() != null);

TA.Utils.Core/AsciiSymbols.cs

@@ -1,11 +1,12 @@
-// This file is part of the TA.NexDome.AscomServer project
-// Copyright © 2019-2019 Tigra Astronomy, all rights reserved.
+// This file is part of the TA.Utils project
+// Copyright © 2016-2020 Tigra Astronomy, all rights reserved.
+// File: AsciiSymbols.cs  Last modified: 2020-07-13@02:11 by Tim Long
+
+#pragma warning disable 1591
 
 namespace TA.Utils.Core
     {
-    /// <summary>
-    ///     Enumeration constants for ASCII control codes.
-    /// </summary>
+    /// <summary>Enumeration constants for ASCII control codes.</summary>
     public enum AsciiSymbols : byte
         {
         // ReSharper disable InconsistentNaming

TA.Utils.Core/AsyncExtensions.cs

@@ -1,5 +1,6 @@
-// This file is part of the TA.NexDome.AscomServer project
-// Copyright © 2019-2019 Tigra Astronomy, all rights reserved.
+// This file is part of the TA.Utils project
+// Copyright © 2016-2020 Tigra Astronomy, all rights reserved.
+// File: AsyncExtensions.cs  Last modified: 2020-07-13@02:11 by Tim Long
 
 using System;
 using System.Runtime.CompilerServices;
@@ -8,29 +9,33 @@
 
 namespace TA.Utils.Core
     {
+    /// <summary>Helper methods for manipulating strings of ASCII-encoded text.</summary>
     public static class AsyncExtensions
         {
         /// <summary>
-        /// Adds cancellation to a task that was otherwise not cancellable.
-        /// Note: the underlying task may still execute to completion.
+        ///     Adds cancellation to a task that was otherwise not cancellable. Note: the underlying task may
+        ///     still execute to completion.
         /// </summary>
         /// <typeparam name="T">The type of result to be returned by the task.</typeparam>
         /// <param name="task">The uncancellable task.</param>
         /// <param name="cancellationToken">The cancellation token that can be used to cancel the task.</param>
         /// <returns>Task{T}.</returns>
-        /// <exception cref="T:System.OperationCanceledException">Thrown if cancellation occurs before the underlying task completes.</exception>
+        /// <exception cref="T:System.OperationCanceledException">
+        ///     Thrown if cancellation occurs before the
+        ///     underlying task completes.
+        /// </exception>
         public static async Task<T> WithCancellation<T>(this Task<T> task, CancellationToken cancellationToken)
             {
             var tcs = new TaskCompletionSource<bool>();
-            using (cancellationToken.Register(s => ((TaskCompletionSource<bool>)s).TrySetResult(true), tcs))
+            using (cancellationToken.Register(s => ((TaskCompletionSource<bool>) s).TrySetResult(true), tcs))
                 if (task != await Task.WhenAny(task, tcs.Task))
                     throw new OperationCanceledException(cancellationToken);
             return task.Result;
             }
 
         /// <summary>
-        /// Configures a task to schedule its completion on any available thread.
-        /// Use this when awaiting tasks in a user interface thread to avoid deadlock issues.
+        ///     Configures a task to schedule its completion on any available thread. Use this when awaiting
+        ///     tasks in a user interface thread to avoid deadlock issues.
         /// </summary>
         /// <typeparam name="TResult">The type of the result.</typeparam>
         /// <param name="task">The task to configure.</param>
@@ -41,8 +46,8 @@ public static ConfiguredTaskAwaitable<TResult> ContinueOnAnyThread<TResult>(this
             }
 
         /// <summary>
-        /// Configures a task to schedule its completion on any available thread.
-        /// Use this when awaiting tasks in a user interface thread to avoid deadlock issues.
+        ///     Configures a task to schedule its completion on any available thread. Use this when awaiting
+        ///     tasks in a user interface thread to avoid deadlock issues.
         /// </summary>
         /// <param name="task">The task to configure.</param>
         /// <returns>An awaitable object that may schedule continuation on any thread.</returns>
@@ -52,15 +57,15 @@ public static ConfiguredTaskAwaitable ContinueOnAnyThread(this Task task)
             }
 
         /// <summary>
-        /// Configures a task awaiter to schedule continuation on the captured synchronization context.
-        /// That is, the continuation should execute on the same thread that created the task.
-        /// This can be risky when the awaiter is a single threaded apartment (STA) thread, such as
-        /// the user interface thread. If the awaiter blocks waiting for the task, then the
-        /// continuation may never execute, resulting in deadlock. Use with care.
+        ///     Configures a task awaiter to schedule continuation on the captured synchronization context.
+        ///     That is, the continuation should execute on the same thread that created the task. This can be
+        ///     risky when the awaiter is a single threaded apartment (STA) thread, such as the user interface
+        ///     thread. If the awaiter blocks waiting for the task, then the continuation may never execute,
+        ///     resulting in deadlock. Use with care.
         /// </summary>
         /// <param name="task">The task.</param>
         /// <returns>ConfiguredTaskAwaitable.</returns>
-        /// <seealso cref="ContinueOnAnyThread"/>
+        /// <seealso cref="ContinueOnAnyThread" />
         public static ConfiguredTaskAwaitable ContinueOnCurrentThread(this Task task)
             {
             return task.ConfigureAwait(continueOnCapturedContext: true);

TA.Utils.Core/DisplayEquivalentAttribute.cs

@@ -1,22 +1,30 @@
-// This file is part of the TA.NexDome.AscomServer project
-// Copyright © 2019-2019 Tigra Astronomy, all rights reserved.
+// This file is part of the TA.Utils project
+// Copyright © 2016-2020 Tigra Astronomy, all rights reserved.
+// File: DisplayEquivalentAttribute.cs  Last modified: 2020-07-13@02:11 by Tim Long
 
 using System;
 
 namespace TA.Utils.Core
     {
     /// <summary>
-    ///     When applied to an enum member or field, specifies a string that should be used for
-    ///     display purposes instead of the identifier name. This can be useful within code that
-    ///     must render HTML markup from an enumerated type.
+    ///     When applied to an enum member or field, specifies a string that should be used for display
+    ///     purposes instead of the identifier name. This can be useful within code that must render HTML
+    ///     markup from an enumerated type.
     /// </summary>
     /// <seealso cref="System.Attribute" />
     /// <seealso cref="EnumExtensions.DisplayEquivalent" />
     [AttributeUsage(AttributeTargets.Field)]
     public sealed class DisplayEquivalentAttribute : Attribute
         {
+        /// <summary>
+        ///     Initializes a new instance of the
+        ///     <see cref="T:TA.Utils.Core.DisplayEquivalentAttribute" /> class.
+        /// </summary>
+        /// <param name="text">The text to be shown on the display instead of the value name.</param>
         public DisplayEquivalentAttribute(string text) => Value = text;
 
+        /// <summary>Gets the display text value.</summary>
+        /// <value>The display text to be used instead of the enumerated value name.</value>
         public string Value { get; }
         }
     }

TA.Utils.Core/EnumExtensions.cs

@@ -1,31 +1,32 @@
-// This file is part of the TA.NexDome.AscomServer project
-// Copyright © 2019-2019 Tigra Astronomy, all rights reserved.
+// This file is part of the TA.Utils project
+// Copyright © 2016-2020 Tigra Astronomy, all rights reserved.
+// File: EnumExtensions.cs  Last modified: 2020-07-13@02:11 by Tim Long
 
 using System;
 using System.Linq;
 using System.Reflection;
 
 namespace TA.Utils.Core
     {
+    /// <summary>Helper methods for use with enumerated types.</summary>
     public static class EnumExtensions
         {
         /// <summary>
-        ///     Returns the equivalent display text for a given Enum value
+        ///     Returns the equivalent display text for a given Enum value. Specifiy display text by placing
+        ///     the <see cref="DisplayEquivalentAttribute" /> attribute on the enumeration's member fields.
         /// </summary>
-        /// <remarks>
-        ///     Inspired by: http://blogs.msdn.com/b/abhinaba/archive/2005/10/21/483337.aspx
-        /// </remarks>
-        /// <param name="en"></param>
-        /// <returns></returns>
-        /// <seealso cref="DisplayEquivalentAttribute"/>
+        /// <remarks>Inspired by: http://blogs.msdn.com/b/abhinaba/archive/2005/10/21/483337.aspx</remarks>
+        /// <param name="en">The enumerated value.</param>
+        /// <returns>Text suitable for use in a display or user interface.</returns>
+        /// <seealso cref="DisplayEquivalentAttribute" />
         public static string DisplayEquivalent(this Enum en)
             {
             string enumValueName = en.ToString();
             var type = en.GetType();
             var fields = type.GetTypeInfo().DeclaredFields;
             var fieldInfo = fields.Single(p => p.Name == enumValueName);
             var attribute =
-                (DisplayEquivalentAttribute)fieldInfo?.GetCustomAttribute(typeof(DisplayEquivalentAttribute));
+                (DisplayEquivalentAttribute) fieldInfo?.GetCustomAttribute(typeof(DisplayEquivalentAttribute));
             if (fieldInfo == null || attribute == null)
                 return enumValueName;
             string displayEquivalent = attribute.Value;

TA.Utils.Core/GitVersion.cs

@@ -1,8 +1,6 @@
 // This file is part of the TA.Utils project
-//
 // Copyright © 2016-2020 Tigra Astronomy, all rights reserved.
-//
-// File: GitVersionExtensions.cs  Last modified: 2020-07-11@19:58 by Tim Long
+// File: GitVersion.cs  Last modified: 2020-07-13@02:11 by Tim Long
 
 using System;
 using System.Linq;
@@ -14,41 +12,76 @@ namespace TA.Utils.Core
     ///     Provides a set of read-only properties for accessing version information that was injected by
     ///     GitVersion as part of the build process.
     /// </summary>
+    /// <seealso cref="SemanticVersion" />
     public static class GitVersion
         {
+        /// <summary>The type injected by GitVersion during the build process, containing version information.</summary>
         private static readonly Type InjectedVersion = ReflectInjectedGitVersionType();
 
-        private static string GitVersionField(this Type gitVersionInformationType, string fieldName)
-            {
-            var versionField = gitVersionInformationType?.GetField(fieldName);
-            return versionField?.GetValue(null).ToString() ?? "undefined";
-            }
-
-        private static Type ReflectInjectedGitVersionType()
-            {
-            var assembly = Assembly.GetEntryAssembly();
-            var type = assembly.GetTypes().SingleOrDefault(t => t.Name == "GitVersionInformation");
-            return type;
-            }
-
+        /// <summary>Gets the git informational version.</summary>
+        /// <value>The git informational version.</value>
+        /// <seealso cref="SemanticVersion" />
         public static string GitInformationalVersion => InjectedVersion.GitVersionField("InformationalVersion");
 
+        /// <summary>Gets the git commit SHA.</summary>
+        /// <value>The git commit SHA.</value>
         public static string GitCommitSha => InjectedVersion.GitVersionField("Sha");
 
+        /// <summary>Gets the git commit short SHA.</summary>
+        /// <value>The git commit short SHA.</value>
         public static string GitCommitShortSha => InjectedVersion.GitVersionField("ShortSha");
 
+        /// <summary>Gets the git commit date.</summary>
+        /// <value>The git commit date.</value>
         public static string GitCommitDate => InjectedVersion.GitVersionField("CommitDate");
 
+        /// <summary>Gets the git semantic version string.</summary>
+        /// <value>The git semantic version string.</value>
+        /// <seealso cref="SemanticVersion" />
         public static string GitSemVer => InjectedVersion.GitVersionField("SemVer");
 
+        /// <summary>Gets the git full semantic version string.</summary>
+        /// <value>The git full semantic version string.</value>
+        /// <seealso cref="SemanticVersion" />
         public static string GitFullSemVer => InjectedVersion.GitVersionField("FullSemVer");
 
+        /// <summary>Gets the git build metadata.</summary>
+        /// <value>The git build metadata string.</value>
+        /// <seealso cref="SemanticVersion" />
         public static string GitBuildMetadata => InjectedVersion.GitVersionField("FullBuildMetaData");
 
+        /// <summary>Gets the git major version.</summary>
+        /// <value>The git major version, as a string.</value>
+        /// <seealso cref="SemanticVersion" />
         public static string GitMajorVersion => InjectedVersion.GitVersionField("Major");
 
+        /// <summary>Gets the git minor version.</summary>
+        /// <value>The git minor version, as a string.</value>
+        /// <seealso cref="SemanticVersion" />
         public static string GitMinorVersion => InjectedVersion.GitVersionField("Minor");
 
+        /// <summary>Gets the git patch version.</summary>
+        /// <value>The git patch version, as a string.</value>
+        /// <seealso cref="SemanticVersion" />
         public static string GitPatchVersion => InjectedVersion.GitVersionField("Patch");
+
+        /// <summary>Uses reflection to fetch the value of a member field of the injected version information.</summary>
+        /// <param name="gitVersionInformationType">Type of the git version information.</param>
+        /// <param name="fieldName">Name of the field.</param>
+        /// <returns>A string containing the field value, or "undefined".</returns>
+        private static string GitVersionField(this Type gitVersionInformationType, string fieldName)
+            {
+            var versionField = gitVersionInformationType?.GetField(fieldName);
+            return versionField?.GetValue(null).ToString() ?? "undefined";
+            }
+
+        /// <summary>Reflects the type of the injected git version information.</summary>
+        /// <returns>Type.</returns>
+        private static Type ReflectInjectedGitVersionType()
+            {
+            var assembly = Assembly.GetEntryAssembly();
+            var type = assembly.GetTypes().SingleOrDefault(t => t.Name == "GitVersionInformation");
+            return type;
+            }
         }
     }

TA.Utils.Core/MathExtensions.cs

@@ -1,14 +1,16 @@
-// This file is part of the TA.NexDome.AscomServer project
-// Copyright © 2019-2019 Tigra Astronomy, all rights reserved.
+// This file is part of the TA.Utils project
+// Copyright © 2016-2020 Tigra Astronomy, all rights reserved.
+// File: MathExtensions.cs  Last modified: 2020-07-13@02:11 by Tim Long
 
 using System;
 
 namespace TA.Utils.Core
     {
+    /// <summary>Helper methods for mathematical constants, operations and algorithms</summary>
     public static class MathExtensions
         {
         /// <summary>Clips (constrains) a value to within the specified range.</summary>
-        /// <typeparam name="T">A type that implements <see cref="IComparable"/>.</typeparam>
+        /// <typeparam name="T">A type that implements <see cref="IComparable" />.</typeparam>
         /// <param name="input">The input value.</param>
         /// <param name="minimum">The minimum allowed value.</param>
         /// <param name="maximum">The maximum allowed value.</param>