From 90ccad7ca819eeb5a23267a550100cf0a67c99bc Mon Sep 17 00:00:00 2001
From: Stuart Blackburn <stuart@dtangl.com>
Date: Wed, 17 Jan 2024 20:23:09 +0000
Subject: [PATCH] task: updates to xml comments

---
 .gitignore                                    |  5 ++
 src/Primitively.Abstractions/ByteAttribute.cs |  4 +-
 src/Primitively.Abstractions/DataType.cs      | 46 +++++++++++++++++++
 .../DateOnlyAttribute.cs                      |  4 +-
 src/Primitively.Abstractions/GuidAttribute.cs |  3 +-
 src/Primitively.Abstractions/IPrimitive.cs    | 26 +++++++++--
 src/Primitively.Abstractions/IPrimitive`1.cs  | 13 ++++++
 src/Primitively.Abstractions/IntAttribute.cs  |  4 +-
 8 files changed, 93 insertions(+), 12 deletions(-)
 create mode 100644 src/Primitively.Abstractions/IPrimitive`1.cs

diff --git a/.gitignore b/.gitignore
index dfcfd56..eb4a98f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -348,3 +348,8 @@ MigrationBackup/
 
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
+
+# DocFx generated files
+/docs/**/toc.yml
+/docs/api/
+_site
diff --git a/src/Primitively.Abstractions/ByteAttribute.cs b/src/Primitively.Abstractions/ByteAttribute.cs
index 8dbbcc7..dfa1335 100644
--- a/src/Primitively.Abstractions/ByteAttribute.cs
+++ b/src/Primitively.Abstractions/ByteAttribute.cs
@@ -3,8 +3,8 @@
 namespace Primitively;
 
 /// <summary>
-///     Make a readonly record struct that encapsulates a Unsigned 8-bit integer primitive value
-///     with a default range of: 0 to 255
+/// Make a readonly record struct that encapsulates a Unsigned 8-bit integer primitive value
+/// with a default range of: 0 to 255
 /// </summary>
 [AttributeUsage(AttributeTargets.Struct, Inherited = false, AllowMultiple = false)]
 [Conditional(Constants.ConditionalCompilationSymbol)]
diff --git a/src/Primitively.Abstractions/DataType.cs b/src/Primitively.Abstractions/DataType.cs
index 18482a9..cd1228e 100644
--- a/src/Primitively.Abstractions/DataType.cs
+++ b/src/Primitively.Abstractions/DataType.cs
@@ -1,16 +1,62 @@
 namespace Primitively;
 
+/// <summary>
+/// Data types supported by Primitively types
+/// </summary>
 public enum DataType
 {
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="Byte"/> value
+    /// </summary>
     Byte,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="DateOnly"/> value
+    /// </summary>
     DateOnly,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="Guid"/> value
+    /// </summary>
     Guid,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="Int"/> value
+    /// </summary>
     Int,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="Long"/> value
+    /// </summary>
     Long,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="SByte"/> value
+    /// </summary>
     SByte,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="Short"/> value
+    /// </summary>
     Short,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="String"/> value
+    /// </summary>
     String,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="UInt"/> value
+    /// </summary>
     UInt,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="ULong"/> value
+    /// </summary>
     ULong,
+
+    /// <summary>
+    /// Represents a Primitively type that encapsulates a <see cref="UShort"/> value
+    /// </summary>
     UShort
 }
diff --git a/src/Primitively.Abstractions/DateOnlyAttribute.cs b/src/Primitively.Abstractions/DateOnlyAttribute.cs
index c2f60cb..5012f80 100644
--- a/src/Primitively.Abstractions/DateOnlyAttribute.cs
+++ b/src/Primitively.Abstractions/DateOnlyAttribute.cs
@@ -3,8 +3,8 @@
 namespace Primitively;
 
 /// <summary>
-///     Make a readonly record struct that encapsulates a DateOnly primitive value
-///     with default Iso8601 format of yyyy-MM-dd
+/// Make a readonly record struct that encapsulates a DateOnly primitive value
+/// with default Iso8601 format of yyyy-MM-dd
 /// </summary>
 [AttributeUsage(AttributeTargets.Struct, Inherited = false, AllowMultiple = false)]
 [Conditional(Constants.ConditionalCompilationSymbol)]
diff --git a/src/Primitively.Abstractions/GuidAttribute.cs b/src/Primitively.Abstractions/GuidAttribute.cs
index 508f87c..a8dee79 100644
--- a/src/Primitively.Abstractions/GuidAttribute.cs
+++ b/src/Primitively.Abstractions/GuidAttribute.cs
@@ -3,7 +3,7 @@
 namespace Primitively;
 
 /// <summary>
-///     Make a readonly record struct that encapsulates a GUID primitive value
+/// Make a readonly record struct that encapsulates a GUID primitive value
 /// </summary>
 [AttributeUsage(AttributeTargets.Struct, Inherited = false, AllowMultiple = false)]
 [Conditional(Constants.ConditionalCompilationSymbol)]
@@ -20,5 +20,6 @@ public GuidAttribute(Specifier specifier)
     }
 
     public Specifier Specifier { get; }
+
     public bool ImplementIValidatableObject { get; set; }
 }
diff --git a/src/Primitively.Abstractions/IPrimitive.cs b/src/Primitively.Abstractions/IPrimitive.cs
index aba4400..9129e4b 100644
--- a/src/Primitively.Abstractions/IPrimitive.cs
+++ b/src/Primitively.Abstractions/IPrimitive.cs
@@ -1,17 +1,33 @@
 namespace Primitively;
 
+/// <summary>
+/// The interface that all source generated Primitively types implement.
+/// </summary>
 public interface IPrimitive
 {
+    /// <summary>
+    /// Flag indicating the instance has a valid value.
+    /// </summary>
+    /// <remarks>
+    /// Attempts to instantiate a Primitively type with an invalid value will result in a default instance with no value.
+    /// </remarks>
     public bool HasValue { get; }
 
+    /// <summary>
+    /// The .net type of the value that the instance encapsulates.
+    /// </summary>
     public Type ValueType { get; }
 
+    /// <summary>
+    /// The <see cref="DataType"/> enum representation of type that the instance encapsulates.
+    /// </summary>
     public DataType DataType { get; }
 
+    /// <summary>
+    /// The value encapsulated by this instance
+    /// </summary>
+    /// <remarks>
+    /// Attempts to instantiate a Primitively type with an invalid value will result in a default instance with no value.
+    /// </remarks>
     public object Value { get; }
 }
-
-public interface IPrimitive<out T> : IPrimitive
-{
-    public new T Value { get; }
-}
diff --git a/src/Primitively.Abstractions/IPrimitive`1.cs b/src/Primitively.Abstractions/IPrimitive`1.cs
new file mode 100644
index 0000000..a0166c8
--- /dev/null
+++ b/src/Primitively.Abstractions/IPrimitive`1.cs
@@ -0,0 +1,13 @@
+namespace Primitively;
+
+/// <summary>
+/// The generic interface that all source generated Primitively types implement
+/// </summary>
+/// <typeparam name="T">The .net type of the encapsulated value</typeparam>
+public interface IPrimitive<out T> : IPrimitive
+{
+    /// <summary>
+    /// The value of the Primitively type 
+    /// </summary>
+    public new T Value { get; }
+}
diff --git a/src/Primitively.Abstractions/IntAttribute.cs b/src/Primitively.Abstractions/IntAttribute.cs
index b11f6d0..e9e2c34 100644
--- a/src/Primitively.Abstractions/IntAttribute.cs
+++ b/src/Primitively.Abstractions/IntAttribute.cs
@@ -3,8 +3,8 @@
 namespace Primitively;
 
 /// <summary>
-///     Make a readonly record struct that encapsulates a Signed 32-bit integer primitive value
-///     with a default range of: -2,147,483,648 to 2,147,483,647
+/// Make a readonly record struct that encapsulates a Signed 32-bit integer primitive value
+/// with a default range of: -2,147,483,648 to 2,147,483,647
 /// </summary>
 [AttributeUsage(AttributeTargets.Struct, Inherited = false, AllowMultiple = false)]
 [Conditional(Constants.ConditionalCompilationSymbol)]