Utf8JsonWriter and JsonElement, redux

[bartonjs]

The original JsonDocument API proposal (#33968) had instance methods on Utf8JsonWriter which could (deeply) write a JsonElement.

-    public partial struct Utf8JsonWriter
-    {
-        public void WriteElement(string propertyName, JsonElement value, bool escape = true);
-        public void WriteElement(ReadOnlySpan<char> propertyName, JsonElement value, bool escape = true);
-        public void WriteElement(ReadOnlySpan<byte> utf8PropertyName, JsonElement value, bool escape = true);
-        public void WriteElementValue(JsonElement element, bool escape = true);
-    }

This was viewed, after the fact, as a layering violation.

The new proposal is

public partial struct JsonElement
{
    public void WriteValueTo(ref Utf8JsonWriter writer);
    public void WriteTo(ref Utf8JsonWriter writer, ReadOnlySpan<char> propertyName);
    public void WriteTo(ref Utf8JsonWriter writer, ReadOnlySpan<byte> utf8PropertyName);
}

Using the Utf8JsonWriter convention that Value is used when not a property, and no extra modifier is used for a property.

[terrajobst]

Video

Usability wise, this proposal seems less than ideal. Not sure I personal buy the layering argument, but if we feel strongly we should rename the method and swap the arguments:

public partial struct JsonElement
{
    public void WriteAsValue(ref Utf8JsonWriter writer);
    public void WriteAsProperty(ReadOnlySpan<char> propertyName, ref Utf8JsonWriter writer);
    public void WriteAsProperty(ReadOnlySpan<byte> utf8PropertyName, ref Utf8JsonWriter writer);
}