Automatically port System.Text.Json.JsonSerializerOptions

[carlossanlop]

New batch.

[rpetrusha]

I've made a number of changes, if you'd like to review them, @carlossanlop. I'll merge when the build completes successfully.

Exception conditions were appearing multiple times in the file. Was there a change to your porting tool that might have caused this?

[carlossanlop]

Exception conditions were appearing multiple times in the file. Was there a change to your porting tool that might have caused this?

@rpetrusha I doubt it, unless you're seeing the same exceptions in all the PRs I submitted for Json yesterday.

What was the error? Maybe it was an intermittent issue in the Docs build?

Edit: I see what you mean. I thought you meant an exception thrown during the build process. Let me check the code.

[jozkee]

Left some comments.

[carlossanlop]

@rpetrusha It's not my tool's fault, I ran it again and all the exceptions were added only once.
It was my own fault when I was fixing the exception messages. They all started with "Thrown when" and used Control+F in VS to remove the additional text. But apparently I did something wrong and also duplicated them all 5 times. Sorry about that. If I find any others, I'll remove them.
CC @jozkee who also reported the problem.

[carlossanlop]

I addressed the comments and fixed some missing values. The only thing blocking this from getting merged is the question to @ahsonkhan

[carlossanlop]

@rpetrusha the last comment in this PR has been addressed. If the build passes, I think we can get this merged.

[ahsonkhan]

Partially reviewed. Left some feedback.

[rpetrusha]

I'll merge this PR now, @carlossanlop.

[ahsonkhan]

This remark got duplicated with the latest change.

[ahsonkhan]

It should state, "should not be modified", not cannot. There is nothing preventing the caller from modifying the list. The changes just won't be reflected when (de)serializing.

cc @steveharter

[steveharter]

The caller cannot modify the list. They will get an InvalidOperationException.

[ahsonkhan]

Really? Interesting. We should document the exception then, no? Similar to other properties:
https://docs.microsoft.com/en-us/dotnet/api/system.text.json.jsonserializeroptions.allowtrailingcommas?view=netcore-3.0#exceptions

Verified, yep.

[Fact]
public static void ConverterWithCallback()
{
    const string json = @"{""Name"":""MyName""}";

    var options = new JsonSerializerOptions();
    options.Converters.Add(new CustomerCallbackConverter());

    Customer customer = JsonSerializer.Deserialize<Customer>(json, options);
    Assert.Equal("MyNameHello!", customer.Name);

    // Throws System.InvalidOperationException : Serializer options cannot be changed once serialization or deserialization has occurred.
    options.Converters.Add(new CustomerCallbackConverter());
}

[ahsonkhan]

This is missing a start tag

Suggested change

	<value><see langword="true" /> to ignore null values during serialization and deserialization; otherwise, see langword="false" />.</value>
	<value><see langword="true" /> to ignore null values during serialization and deserialization; otherwise, <see langword="false" />.</value>

[ahsonkhan]

Why do we have "the default value" specified in the summary text in some cases, but in remarks in others. Worth being consistent and moving them all to the remarks?

[ahsonkhan]

Suggested change

	There is a performance cost associated with case-insensitie comparison (that is, when `PropertyNameCaseInsensitive` is `true`).
	There is a performance cost associated with case-insensitive comparison (that is, when `PropertyNameCaseInsensitive` is `true`).

[ahsonkhan]

JsonNamingPolicy is not an enum.

Suggested change

	<value>One of the enum values from <see cref="T:System.Text.Json.JsonNamingPolicy" />.</value>
	<value>An instance of a <see cref="T:System.Text.Json.JsonNamingPolicy" />.</value>

[ahsonkhan]

The enum value JsonCommentHandling.Allow isn't supported here.

Suggested change

	<value>A value that indicates whether comments are allowed, disallowed, or skipped.</value>
	<value>A value that indicates whether comments are disallowed or ignored.</value>

[ahsonkhan]

"JSON using pretty printing" doesn't make sense.

Suggested change

	<summary>Gets or sets a value that defines whether JSON should use pretty printing. By default, JSON is serialized without any extra white space.</summary>
	<summary>Gets or sets a value that defines whether JSON should be written pretty printed. By default, JSON is serialized without any extra white space.</summary>

[ahsonkhan]

Suggested change

	- Adding new lines
	- Adding new lines between between consecutive JSON object or array elements.

[ahsonkhan]

Left some correctness feedback/typos.