Skip to content

Clarify documentation: three approaches, explicit terminology, STJ source generator#6

Merged
ScarletKuro merged 3 commits intomasterfrom
copilot/fix-attribute-resolution-issue
Jan 16, 2026
Merged

Clarify documentation: three approaches, explicit terminology, STJ source generator#6
ScarletKuro merged 3 commits intomasterfrom
copilot/fix-attribute-resolution-issue

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Jan 16, 2026

The Overview section incorrectly listed JsonDateTimeFormatAttribute and DateTimeConverterResolver as separate approaches when they must be used together. Generic terms like "source generator" and "resolver" lacked precision. JsonDateTimeFormatConverter<T> was documented as source generator-only despite supporting reflection.

Changes

  • Overview restructured from 4 to 3 approaches: Combined JsonDateTimeFormatAttribute + DateTimeConverterResolver as a single approach since the attribute is non-functional without the resolver
  • Explicit terminology: "System.Text.Json source generator" replaces "source generator"; "DateTimeConverterResolver" replaces "resolver"
  • JsonDateTimeFormatConverter clarified: Now documents support for both reflection-based and source generator scenarios; added "Does not require DateTimeConverterResolver" to pros
  • Consistency: Updated all references throughout Prerequisites, Quick Start, Usage Scenarios, Available Components, and Quirks sections

Example

Before:

2. **`JsonDateTimeFormatAttribute`** - Clean attribute for source generators with .NET 9+ resolver (no warnings)
4. **`DateTimeConverterResolver`** - Contract customization for .NET 9+ source generators

After:

2. **`JsonDateTimeFormatAttribute` + `DateTimeConverterResolver`** - Clean attribute-based approach for System.Text.Json source generator with .NET 9+ (no warnings)
Original prompt

I think that overview that copilot created is a little bit off

## Overview

This package provides four ways to specify custom date formats for `DateTime`, `DateTimeOffset`, `DateOnly`, `TimeOnly`, and their nullable counterparts when serializing and deserializing JSON using `System.Text.Json`:

1. **`JsonDateTimeConverterAttribute`** - Simple attribute-based approach (reflection only, or .NET 9+ with resolver but produces warnings)
2. **`JsonDateTimeFormatAttribute`** - Clean attribute for source generators with .NET 9+ resolver (no warnings)
3. **`JsonDateTimeFormatConverter<T>`** - Type-safe converter for source generators (all .NET versions)
4. **`DateTimeConverterResolver`** - Contract customization for .NET 9+ source generators

That JsonDateTimeFormatAttribute can only work in conjuction when used with DateTimeConverterResolver
Mentioning the JsonDateTimeFormatAttribute and DateTimeConverterResolver seperatly is awkward, because the
JsonDateTimeFormatAttribute without DateTimeConverterResolver doesn't do anything.
"Simple attribute-based approach (reflection only, or .NET 9+ with resolver but produces warnings)" also is akward first of all instead of "resolved" should use
word DateTimeConverterResolver directly, also it's or with source generator net 9+ using the DateTimeConverterResolver just make the it all professional for the docs.
"4. DateTimeConverterResolver - Contract customization for .NET 9+ source generators" i think everywhere there is says source gen is better to specify that we are talking about STJ sourcegen https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/source-generation

Also in section "Source Generator with Format Converter (.NET 6+)" there is another Pros that
it doesn't require any DateTimeConverterResolver, it will just work if you use it with the normal JsonSerializerContext
it works both sourcegenerator and reflection based

so i guess here: 3. JsonDateTimeFormatConverter<T> - Type-safe converter for source generators (all .NET versions)
you could mention it all version and reflcetion and sourcegen


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

…ext.Json source generator

Co-authored-by: ScarletKuro <19953225+ScarletKuro@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix documentation on JsonDateTimeFormatAttribute usage Clarify documentation: three approaches, explicit terminology, STJ source generator Jan 16, 2026
Copilot AI requested a review from ScarletKuro January 16, 2026 01:26
@codecov
Copy link
Copy Markdown

codecov bot commented Jan 16, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.30%. Comparing base (192c762) to head (9f411a9).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master       #6   +/-   ##
=======================================
  Coverage   92.30%   92.30%           
=======================================
  Files          13       13           
  Lines         156      156           
  Branches       35       35           
=======================================
  Hits          144      144           
  Misses          7        7           
  Partials        5        5           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ScarletKuro ScarletKuro marked this pull request as ready for review January 16, 2026 01:32
@ScarletKuro ScarletKuro merged commit 89efb30 into master Jan 16, 2026
3 checks passed
@ScarletKuro ScarletKuro deleted the copilot/fix-attribute-resolution-issue branch January 16, 2026 01:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants