Update README and xmldoc

Author: ScarletKuro

README.md

@@ -6,6 +6,9 @@
 The `JsonDateTimeConverterAttribute` allows you to specify a custom date format for `DateTime`, `DateTimeOffset`, and their nullable counterparts when serializing and deserializing JSON using `System.Text.Json`. This ensures consistency in how date and time values are handled across your application.
 
 ## Installation
+```bash
+dotnet add package Scarlet.System.Text.Json.DateTimeConverter
+```
 
 Ensure you have the necessary .NET target framework installed. This attribute is compatible with:
 - .NET 6
@@ -17,10 +20,6 @@ Ensure you have the necessary .NET target framework installed. This attribute is
 ### Example Model
 
 ```csharp
-using System;
-using System.Text.Json.Serialization;
-using Scarlet.System.Text.Json.DateTimeConverter;
-
 public class MyModel
 {
     [JsonDateTimeConverter("yyyy-MM-dd")]
@@ -34,9 +33,6 @@ public class MyModel
 ### Example Program
 
 ```csharp
-using System;
-using System.Text.Json;
-
 public class Program
 {
     public static void Main()
@@ -59,7 +55,64 @@ public class Program
 }
 ```
 
+### Source Generator Example
+
+If you are using source generators with `System.Text.Json`, you should use `JsonDateTimeFormatConverter` instead of `JsonDateTimeConverterAttribute`.
+
+#### Example Model
+
+```csharp
+public class MyModelSourceGenerator
+{
+    [JsonConverter(typeof(JsonDateTimeFormatConverter<JsonDateTimeFormat.DateTimeFormat>))]
+    public DateTime Date { get; set; }
+
+    [JsonConverter(typeof(JsonDateTimeFormatConverter<JsonDateTimeFormat.DateTimeOffsetFormat>))]
+    public DateTimeOffset DateTimeOffset { get; set; }
+}
+
+internal class JsonDateTimeFormat
+{
+    internal class DateTimeOffsetFormat : IJsonDateTimeFormat
+    {
+        public static string Format => "yyyy-MM-ddTHH:mm:ss.fffZ";
+    }
+    
+    internal class DateTimeFormat : IJsonDateTimeFormat
+    {
+        public static string Format => "yyyy-MM-ddTHH:mm:ss";
+    }
+}
+
+[JsonSerializable(typeof(MyModelSourceGenerator))]
+public sealed partial class MyModelSourceGeneratorJsonSerializerContext : JsonSerializerContext;
+
+public class Program
+{
+    public static void Main()
+    {
+        var modelType = typeof(MyModelSourceGenerator);
+        var model = new MyModelSourceGenerator
+        {
+            Date = DateTime.Now,
+            DateTimeOffset = DateTimeOffset.Now
+        };
+
+        var context = MyModelSourceGeneratorJsonSerializerContext.Default;
+
+        // Serialize
+        string jsonString = JsonSerializer.Serialize(model, modelType, context);
+        Console.WriteLine($"Serialized JSON: {jsonString}");
+
+        // Deserialize
+        var deserializedModel = (MyModelSourceGenerator?)JsonSerializer.Deserialize(jsonString, modelType, context);
+        Console.WriteLine($"Deserialized Date: {deserializedModel.Date}");
+        Console.WriteLine($"Deserialized DateTimeOffset: {deserializedModel.DateTimeOffset}");
+    }
+}
+```
+
 ## Notes
 
-- The `JsonDateTimeConverterAttribute` can be applied to properties of type `DateTime`, `DateTime?`, `DateTimeOffset`, and `DateTimeOffset?`.
+- The `JsonDateTimeConverterAttribute` and `JsonDateTimeFormatConverter` can be applied to properties of type `DateTime`, `DateTime?`, `DateTimeOffset`, and `DateTimeOffset?`.
 - The format string provided to the attribute should follow the standard date and time format strings in .NET.

src/Scarlet.System.Text.Json.DateTimeConverter.Tests/Scarlet.System.Text.Json.DateTimeConverter.Tests.csproj

@@ -1,10 +1,10 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-
+    <LangVersion>latest</LangVersion>
     <IsPackable>false</IsPackable>
     <IsTestProject>true</IsTestProject>
   </PropertyGroup>

src/Scarlet.System.Text.Json.DateTimeConverter/IJsonDateTimeFormat.cs

@@ -1,6 +1,17 @@
 namespace Scarlet.System.Text.Json.DateTimeConverter;
 
+/// <summary>
+/// Defines a contract for specifying a custom date format for JSON serialization and deserialization.
+/// </summary>
+/// <remarks>
+/// This interface is used when you want to use source generator `System.Text.Json`, but it also works with non-source generator (reflection-based) serialization and deserialization.
+/// </remarks>
 public interface IJsonDateTimeFormat
 {
+#pragma warning disable CA2252
+    /// <summary>
+    /// Gets the date format string to be used for JSON serialization and deserialization.
+    /// </summary>
     static abstract string Format { get; }
-}
+#pragma warning restore CA2252
+}

src/Scarlet.System.Text.Json.DateTimeConverter/JsonDateTimeConverterAttribute.cs

@@ -5,8 +5,25 @@ namespace Scarlet.System.Text.Json.DateTimeConverter;
 /// <summary>
 /// Specifies that a <see cref="DateTime"/>, <see cref="DateTimeOffset"/> (including Nullables) should be converted using a custom date format.
 /// </summary>
+/// <remarks>
+/// This attribute does not work with `System.Text.Json` source generator. If you use it with <see cref="JsonSerializerContext"/>, you will get SYSLIB1223. 
+/// Attributes deriving from <see cref="JsonConverterAttribute"/> are not supported by the source generator. You should use the <see cref="JsonDateTimeFormatConverter{T}"/> instead.
+/// </remarks>
+/// <example>
+/// Example usage:
+/// <code>
+/// public class Model
+/// {
+///     [JsonDateTimeConverter("yyyy-MM-ddTHH:mm:ss.fffZ")]
+///     public DateTimeOffset DateTimeOffsetProperty { get; set; }
+/// }
+/// </code>
+/// </example>
 public sealed class JsonDateTimeConverterAttribute : JsonConverterAttribute
 {
+    /// <summary>
+    /// The date format string.
+    /// </summary>
     public string Format { get; }
 
     /// <summary>

src/Scarlet.System.Text.Json.DateTimeConverter/JsonDateTimeFormatConverter.cs

@@ -3,8 +3,37 @@
 
 namespace Scarlet.System.Text.Json.DateTimeConverter;
 
+/// <summary>
+/// A JSON converter factory that creates converters for <see cref="DateTime"/> and <see cref="DateTimeOffset"/> types using a specified date format.
+/// </summary>
+/// <typeparam name="T">The type that implements <see cref="IJsonDateTimeFormat"/> to provide the date format.</typeparam>
+/// <remarks>
+/// This converter is used when you want to use source generator `System.Text.Json`, but it also works with non-source generator (reflection-based) serialization and deserialization.
+/// </remarks>
+/// <example>
+/// Example usage:
+/// <code>
+/// public class Model
+/// {
+///     [JsonConverter(typeof(JsonDateTimeFormatConverter&lt;JsonDateTimeFormat.DateTimeOffsetFormat&gt;))]
+///     public DateTimeOffset DateTimeOffsetProperty { get; set; }
+/// }
+/// internal class JsonDateTimeFormat
+/// {
+///     internal class DateTimeOffsetFormat : IJsonDateTimeFormat
+///     {
+///         public static string Format => "yyyy-MM-ddTHH:mm:ss.fffZ";
+///     }
+/// }
+/// </code>
+/// </example>
 public class JsonDateTimeFormatConverter<T> : JsonConverterFactory where T : IJsonDateTimeFormat
 {
+    /// <summary>
+    /// Determines whether the specified type can be converted.
+    /// </summary>
+    /// <param name="typeToConvert">The type to convert.</param>
+    /// <returns><c>true</c> if the type can be converted; otherwise, <c>false</c>.</returns>
     public override bool CanConvert(Type typeToConvert)
     {
         return typeToConvert == typeof(DateTime) ||
@@ -13,6 +42,12 @@ public override bool CanConvert(Type typeToConvert)
                typeToConvert == typeof(DateTimeOffset?);
     }
 
+    /// <summary>
+    /// Creates a converter for the specified type.
+    /// </summary>
+    /// <param name="typeToConvert">The type to convert.</param>
+    /// <param name="options">The serializer options.</param>
+    /// <returns>A <see cref="JsonConverter"/> for the specified type.</returns>
     public override JsonConverter CreateConverter(Type typeToConvert, JsonSerializerOptions options)
     {
         ArgumentNullException.ThrowIfNull(typeToConvert);
@@ -23,6 +58,3 @@ public override JsonConverter CreateConverter(Type typeToConvert, JsonSerializer
         return converter;
     }
 }
-
-
-

src/Scarlet.System.Text.Json.DateTimeConverter/Scarlet.System.Text.Json.DateTimeConverter.csproj

@@ -4,7 +4,7 @@
     <TargetFrameworks>net6.0;net7.0;net8.0</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <LangVersion>preview</LangVersion>
+    <LangVersion>latest</LangVersion>
   </PropertyGroup>
 
   <PropertyGroup>