Fix XML docs and update for release

Author: buvinghausen

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright © 2024 Brian Buvinghausen
+Copyright © 2025 Brian Buvinghausen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

src/Directory.Build.props

@@ -1,10 +1,10 @@
 <Project>
 
   <PropertyGroup>
-    <TargetFrameworks>net8.0;net6.0;netstandard2.1;netstandard2.0;net462</TargetFrameworks>
+    <TargetFrameworks>net9.0;net8.0;netstandard2.1;netstandard2.0;net462</TargetFrameworks>
     <Authors>Brian Buvinghausen</Authors>
     <Company>Buvinghausen Solutions</Company>
-    <Copyright>Copyright © 2024 Brian Buvinghausen</Copyright>
+    <Copyright>Copyright © 2025 Brian Buvinghausen</Copyright>
     <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageProjectUrl>https://github.com/buvinghausen/SequentialGuid/blob/master/README.md</PackageProjectUrl>

src/SequentialGuid.MongoDB/ExtensionMethods.cs

@@ -3,14 +3,21 @@
 namespace SequentialGuid.MongoDB;
 
 /// <summary>
-///     Helper method to make registering the generator easier
+/// Provides extension methods for integrating SequentialGuid functionality with MongoDB.
 /// </summary>
 public static class ExtensionMethods
 {
 	/// <summary>
-	/// Registers SequentialGuidGenerator with the Mongo BsonSerializer for all Guid types
+	/// Registers the <see cref="MongoSequentialGuidGenerator"/> as the ID generator for <see cref="Guid"/> types in MongoDB.
 	/// </summary>
-	/// <param name="generator"></param>
-	public static void RegisterMongoIdGenerator(this SequentialGuidGenerator generator) =>
+	/// <param name="generator">
+	/// The instance of <see cref="MongoSequentialGuidGenerator"/> to be registered as the ID generator.
+	/// </param>
+	/// <remarks>
+	/// This method integrates the <see cref="MongoSequentialGuidGenerator"/> with MongoDB's BSON serialization framework,
+	/// enabling the generation of sequential <see cref="Guid"/> values for MongoDB documents.
+	/// Sequential GUIDs can improve database indexing performance by reducing fragmentation.
+	/// </remarks>
+	public static void RegisterMongoIdGenerator(this MongoSequentialGuidGenerator generator) =>
 		BsonSerializer.RegisterIdGenerator(typeof(Guid), generator);
 }

src/SequentialGuid.MongoDB/SequentialGuidGenerator.cs

@@ -3,29 +3,52 @@
 namespace SequentialGuid.MongoDB;
 
 /// <summary>
-///     Implementation of the <see cref="IIdGenerator" /> interface so it can be used by the Mongo driver
+/// Provides a mechanism for generating sequential <see cref="Guid"/> values specifically for use with MongoDB.
 /// </summary>
-public sealed class SequentialGuidGenerator : IIdGenerator
+/// <remarks>
+/// The <see cref="MongoSequentialGuidGenerator"/> class is designed to integrate seamlessly with MongoDB's BSON serialization framework.
+/// It generates sequential <see cref="Guid"/> values to improve database indexing performance by reducing fragmentation.
+/// This class implements the <see cref="IIdGenerator"/> interface, making it compatible with MongoDB's ID generation system.
+/// </remarks>
+public sealed class MongoSequentialGuidGenerator : IIdGenerator
 {
 	/// <summary>
-	///     Gets an instance of SequentialGuidGenerator helpful for calling the registration method
+	/// Gets the singleton instance of the <see cref="SequentialGuidGenerator"/> class.
 	/// </summary>
-	public static SequentialGuidGenerator Instance { get; } = new();
-
+	/// <value>
+	/// The singleton instance of <see cref="SequentialGuidGenerator"/>.
+	/// </value>
+	/// <remarks>
+	/// This property provides a globally accessible instance of the <see cref="MongoSequentialGuidGenerator"/>.
+	/// It is designed to integrate seamlessly with MongoDB's BSON serialization framework, enabling the generation
+	/// of sequential <see cref="Guid"/> values for improved database indexing performance.
+	/// </remarks>
+	public static MongoSequentialGuidGenerator Instance { get; } = new();
+	
 	/// <summary>
-	/// Function to generate value for the _id property when it was empty
+	/// Generates a new sequential <see cref="Guid"/> to be used as an identifier for a MongoDB document.
 	/// </summary>
-	/// <param name="container">Not used</param>
-	/// <param name="document">Not used</param>
-	/// <returns>sequential guid</returns>
+	/// <param name="container">The container object that holds the document. This parameter is not used in the implementation.</param>
+	/// <param name="document">The document for which the ID is being generated. This parameter is not used in the implementation.</param>
+	/// <returns>A new sequential <see cref="Guid"/>.</returns>
+	/// <remarks>
+	/// This method utilizes the <see cref="SequentialGuidGenerator"/> to generate a sequential <see cref="Guid"/>.
+	/// Sequential GUIDs are designed to improve performance in scenarios such as database indexing by reducing fragmentation.
+	/// </remarks>
 	public object GenerateId(object container, object document) =>
-		SequentialGuid.SequentialGuidGenerator.Instance.NewGuid();
-
+		SequentialGuidGenerator.Instance.NewGuid();
+	
 	/// <summary>
-	///     Checks to see if existing value is empty and needs to be replaced
+	/// Determines whether the specified identifier is considered empty.
 	/// </summary>
-	/// <param name="id">Current value from the document</param>
-	/// <returns>True or false on if GenerateId needs to be invoked</returns>
+	/// <param name="id">The identifier to evaluate. This can be of any type.</param>
+	/// <returns>
+	/// <c>true</c> if the <paramref name="id"/> is either not a <see cref="Guid"/> or is an empty <see cref="Guid"/>; otherwise, <c>false</c>.
+	/// </returns>
+	/// <remarks>
+	/// This method checks if the provided <paramref name="id"/> is either not a <see cref="Guid"/> or represents an empty <see cref="Guid"/> value.
+	/// It is useful for validating identifiers in scenarios where <see cref="Guid"/> values are expected.
+	/// </remarks>
 	public bool IsEmpty(object id) =>
 		id is not Guid guid || guid == Guid.Empty;
 	// Pattern matching is life

src/SequentialGuid.NodaTime/ExtensionMethods.cs

@@ -5,59 +5,108 @@
 namespace NodaTime;
 
 /// <summary>
-///     Helper functions that utilize NodaTime's Instant struct rather than DateTime
+/// Provides extension methods for working with NodaTime's <see cref="Instant"/> and sequential GUID generators.
 /// </summary>
+/// <remarks>
+/// This static class contains helper methods to facilitate the creation of sequential GUIDs and 
+/// conversions between <see cref="Instant"/> and GUID-related types.
+/// </remarks>
 public static class ExtensionMethods
 {
 	/// <summary>
-	/// Takes an instance of NodaTime's Instant struct and returns back a sequential guid
+	/// Generates a new sequential <see cref="Guid"/> based on the specified <see cref="Instant"/> timestamp.
 	/// </summary>
-	/// <param name="generator">Extension parameter the singleton instance of the generator</param>
-	/// <param name="timestamp">Time value in UTC between the Unix epoch and now</param>
-	/// <returns>sequential guid</returns>
+	/// <param name="generator">
+	/// The <see cref="SequentialGuidGenerator"/> instance used to generate the sequential <see cref="Guid"/>.
+	/// </param>
+	/// <param name="timestamp">
+	/// The <see cref="Instant"/> representing the point in time to base the GUID generation on.
+	/// </param>
+	/// <returns>
+	/// A new sequential <see cref="Guid"/> generated using the provided <paramref name="timestamp"/>.
+	/// </returns>
+	/// <remarks>
+	/// This method converts the provided <see cref="Instant"/> to a UTC <see cref="DateTime"/> and uses it
+	/// to generate a sequential <see cref="Guid"/>. Sequential GUIDs are particularly useful for database
+	/// indexing and reducing fragmentation.
+	/// </remarks>
+	/// <exception cref="ArgumentException">
+	/// Thrown if the <paramref name="timestamp"/> is outside the valid range for GUID generation.
+	/// </exception>
 	public static Guid NewGuid(this SequentialGuidGenerator generator, Instant timestamp) =>
 		generator.NewGuid(timestamp.ToDateTimeUtc());
-
+	
 	/// <summary>
-	/// Takes an instance of NodaTime's Instant struct and returns back a sequential guid sorted for SQL Server
+	/// Generates a new sequential <see cref="Guid"/> based on the provided <see cref="Instant"/> timestamp.
 	/// </summary>
-	/// <param name="generator">Extension parameter the singleton instance of the generator</param>
-	/// <param name="timestamp">Time value in UTC between the Unix epoch and now</param>
-	/// <returns>sequential guid for SQL Server</returns>
+	/// <param name="generator">
+	/// The <see cref="SequentialSqlGuidGenerator"/> instance used to generate the sequential GUID.
+	/// </param>
+	/// <param name="timestamp">
+	/// The <see cref="Instant"/> representing the timestamp to base the GUID generation on.
+	/// </param>
+	/// <returns>
+	/// A new sequential <see cref="Guid"/> generated using the specified timestamp.
+	/// </returns>
+	/// <remarks>
+	/// This method converts the provided <see cref="Instant"/> to a UTC <see cref="DateTime"/> and uses it
+	/// to generate a sequential GUID. Sequential GUIDs are particularly useful in scenarios where maintaining
+	/// index performance in databases is critical.
+	/// </remarks>
+	/// <exception cref="ArgumentException">
+	/// Thrown if the <paramref name="timestamp"/> is outside the valid range for GUID generation.
+	/// </exception>
 	public static Guid NewGuid(this SequentialSqlGuidGenerator generator, Instant timestamp) =>
 		generator.NewGuid(timestamp.ToDateTimeUtc());
-
+	
 	/// <summary>
-	/// Takes an instance of NodaTime's Instant struct and returns back a sequential SQL guid
+	/// Generates a new sequential <see cref="SqlGuid"/> based on the specified <see cref="Instant"/> timestamp.
 	/// </summary>
-	/// <param name="generator">Extension parameter the singleton instance of the generator</param>
-	/// <param name="timestamp">Time value in UTC between the Unix epoch and now</param>
-	/// <returns>sequential SQL guid</returns>
+	/// <param name="generator">
+	/// The <see cref="SequentialSqlGuidGenerator"/> instance used to create the sequential <see cref="SqlGuid"/>.
+	/// </param>
+	/// <param name="timestamp">
+	/// The <see cref="Instant"/> representing the point in time to base the sequential <see cref="SqlGuid"/> on.
+	/// </param>
+	/// <returns>
+	/// A new sequential <see cref="SqlGuid"/> corresponding to the provided <see cref="Instant"/>.
+	/// </returns>
+	/// <remarks>
+	/// This method facilitates the creation of sequential <see cref="SqlGuid"/> values, which are particularly
+	/// useful in database scenarios where maintaining index performance is critical. The <paramref name="timestamp"/>
+	/// is converted to a <see cref="DateTime"/> in UTC before generating the <see cref="SqlGuid"/>.
+	/// </remarks>
 	public static SqlGuid NewSqlGuid(this SequentialSqlGuidGenerator generator, Instant timestamp) =>
 		generator.NewSqlGuid(timestamp.ToDateTimeUtc());
 
 	/// <summary>
-	///     Will return the value of SystemClock.Instance.GetCurrentInstant() at the time of the generation of the Guid will
-	///     keep you from needing to store separate audit fields
+	/// Converts a <see cref="Guid"/> to a <see cref="NodaTime.Instant"/> if the <see cref="Guid"/> contains a valid timestamp.
 	/// </summary>
-	/// <param name="id">A sequential Guid with the first 8 bytes containing the system ticks at time of generation</param>
-	/// <returns>Instant?</returns>
+	/// <param name="id">The <see cref="Guid"/> to extract the timestamp from.</param>
+	/// <returns>
+	/// An <see cref="NodaTime.Instant"/> representing the timestamp embedded in the <see cref="Guid"/>, 
+	/// or <c>null</c> if the <see cref="Guid"/> does not contain a valid timestamp.
+	/// </returns>
 	public static Instant? ToInstant(this Guid id) =>
 		id.ToDateTime().ToInstant();
 
 	/// <summary>
-	///     Will return the value of SystemClock.Instance.GetCurrentInstant() at the time of the generation of the Guid will
-	///     keep you from needing to store separate audit fields
+	/// Converts a <see cref="SqlGuid"/> to a nullable <see cref="NodaTime.Instant"/>.
 	/// </summary>
-	/// <param name="sqlGuid">
-	///     A sequential SqlGuid with the first sorted 8 bytes containing the system ticks at time of
-	///     generation
-	/// </param>
-	/// <returns>Instant?</returns>
+	/// <param name="sqlGuid">The <see cref="SqlGuid"/> to convert.</param>
+	/// <returns>
+	/// A nullable <see cref="NodaTime.Instant"/> representing the timestamp embedded in the <see cref="SqlGuid"/>, 
+	/// or <c>null</c> if the <see cref="SqlGuid"/> does not contain a valid timestamp.
+	/// </returns>
+	/// <remarks>
+	/// This method extracts the timestamp from the provided <see cref="SqlGuid"/> and converts it to a 
+	/// <see cref="NodaTime.Instant"/>. If the <see cref="SqlGuid"/> does not contain a valid timestamp, 
+	/// the method returns <c>null</c>.
+	/// </remarks>
 	public static Instant? ToInstant(this SqlGuid sqlGuid) =>
 		sqlGuid.ToDateTime().ToInstant();
 
 	// Helper function to prevent code duplication all it does is conditionally convert a nullable datetime to a nullable instant
 	private static Instant? ToInstant(this DateTime? value) =>
-		value.HasValue ? Instant.FromDateTimeUtc(value.Value) : default(Instant?);
+		value.HasValue ? Instant.FromDateTimeUtc(value.Value) : null;
 }

src/SequentialGuid/SequentialGuidExtensions.cs

@@ -7,8 +7,8 @@
 namespace System;
 
 /// <summary>
-///     Provides extension methods to return back timestamps from a guid as well as convert to &amp; from normal sorting
-///     and SQL Server sorting
+/// Provides extension methods for working with <see cref="Guid"/> and <see cref="SqlGuid"/> objects, 
+/// including conversions and operations related to timestamps and SQL Server sorting order.
 /// </summary>
 public static class SequentialGuidExtensions
 {
@@ -35,11 +35,13 @@ private static DateTime ToDateTime(this long ticks) =>
 		new(ticks, DateTimeKind.Utc);
 
 	/// <summary>
-	///     Will return the value of DateTime.UtcNow at the time of the generation of the Guid will keep you from storing
-	///     separate audit fields
+	/// Converts a <see cref="Guid"/> to a <see cref="DateTime"/> if the <see cref="Guid"/> contains a valid timestamp.
 	/// </summary>
-	/// <param name="id">A sequential Guid with the first 8 bytes containing the system ticks at time of generation</param>
-	/// <returns>DateTime?</returns>
+	/// <param name="id">The <see cref="Guid"/> to extract the timestamp from.</param>
+	/// <returns>
+	/// A <see cref="DateTime"/> representing the timestamp embedded in the <see cref="Guid"/>, 
+	/// or <c>null</c> if the <see cref="Guid"/> does not contain a valid timestamp.
+	/// </returns>
 	public static DateTime? ToDateTime(this Guid id)
 	{
 		var ticks = id.ToTicks();
@@ -49,26 +51,25 @@ private static DateTime ToDateTime(this long ticks) =>
 		ticks = new SqlGuid(id).ToGuid().ToTicks();
 		return ticks.IsDateTime()
 			? ticks.ToDateTime()
-			: default(DateTime?);
+			: null;
 	}
 
 	/// <summary>
-	///     Will return the value of DateTime.UtcNow at the time of the generation of the Guid will keep you from storing
-	///     separate audit fields
+	/// Converts a <see cref="SqlGuid"/> to a <see cref="DateTime"/> if the <see cref="SqlGuid"/> contains a valid timestamp.
 	/// </summary>
-	/// <param name="sqlGuid">
-	///     A sequential SqlGuid with the first sorted 8 bytes containing the system ticks at time of
-	///     generation
-	/// </param>
-	/// <returns>DateTime?</returns>
+	/// <param name="sqlGuid">The <see cref="SqlGuid"/> to extract the timestamp from.</param>
+	/// <returns>
+	/// A <see cref="DateTime"/> representing the timestamp embedded in the <see cref="SqlGuid"/>, 
+	/// or <c>null</c> if the <see cref="SqlGuid"/> does not contain a valid timestamp.
+	/// </returns>
 	public static DateTime? ToDateTime(this SqlGuid sqlGuid) =>
 		sqlGuid.ToGuid().ToDateTime();
 
 	/// <summary>
-	///     Will take a SqlGuid and re-sequence to a Guid that will sort in the same order
+	/// Converts a <see cref="SqlGuid"/> to a <see cref="Guid"/>.
 	/// </summary>
-	/// <param name="sqlGuid">Any SqlGuid</param>
-	/// <returns>Guid</returns>
+	/// <param name="sqlGuid">The <see cref="SqlGuid"/> to convert.</param>
+	/// <returns>A <see cref="Guid"/> representation of the specified <see cref="SqlGuid"/>.</returns>
 	public static Guid ToGuid(this SqlGuid sqlGuid)
 	{
 		var bytes = sqlGuid.ToByteArray()
@@ -80,11 +81,11 @@ public static Guid ToGuid(this SqlGuid sqlGuid)
 	}
 
 	/// <summary>
-	///     Will take a Guid and will re-sequence it so that it will sort properly in SQL Server without fragmenting your
-	///     tables
+	/// Converts a <see cref="Guid"/> to a <see cref="SqlGuid"/> by rearranging its byte order
+	/// to match the sorting order used by SQL Server.
 	/// </summary>
-	/// <param name="id">Any Guid</param>
-	/// <returns>SqlGuid</returns>
+	/// <param name="id">The <see cref="Guid"/> to convert.</param>
+	/// <returns>A <see cref="SqlGuid"/> representation of the provided <see cref="Guid"/>.</returns>
 	public static SqlGuid ToSqlGuid(this Guid id)
 	{
 		var bytes = id.ToByteArray();

src/SequentialGuid/SequentialGuidGenerator.cs

@@ -1,6 +1,14 @@
 namespace SequentialGuid;
 
-/// <inheritdoc />
+/// <summary>
+/// Represents a generator for creating sequential <see cref="Guid"/> values.
+/// </summary>
+/// <remarks>
+/// This sealed class inherits from <see cref="SequentialGuidGeneratorBase{T}"/> and provides
+/// an implementation for generating sequential GUIDs. Sequential GUIDs are particularly useful
+/// in scenarios where GUIDs are used as primary keys in databases, as they can improve indexing
+/// performance by reducing fragmentation.
+/// </remarks>
 public sealed class SequentialGuidGenerator : SequentialGuidGeneratorBase<SequentialGuidGenerator>
 {
 	private SequentialGuidGenerator() { }