Follow-up to #14208 (#14439)

Author: tdykstra

docs/standard/serialization/system-text-json-how-to.md

@@ -1,6 +1,8 @@
 ---
 title: "How to serialize JSON - .NET"
-ms.date: "09/02/2019"
+author: tdykstra
+ms.author: tdykstra
+ms.date: "09/16/2019"
 helpviewer_keywords: 
   - "JSON serialization"
   - "serializing objects"
@@ -17,7 +19,7 @@ This article shows how to use the <xref:System.Text.Json> namespace to serialize
 
 ## Namespaces
 
-The <xref:System.Text.Json> namespace contains all the entry points and the main types. The <xref:System.Text.Json.Serialization> namespace contains attributes and APIs for advanced scenarios and customization specific to serialization and deserialization. Therefore the code examples shown in this article require one or both of the following `using` directives:
+The <xref:System.Text.Json> namespace contains all the entry points and the main types. The <xref:System.Text.Json.Serialization> namespace contains attributes and APIs for advanced scenarios and customization specific to serialization and deserialization. Therefore, the code examples shown in this article require one or both of the following `using` directives:
 
 ```csharp
 using System.Text.Json;
@@ -28,14 +30,18 @@ Attributes from the <xref:System.Runtime.Serialization> namespace aren't current
 
 ## How to write .NET objects to JSON (serialize)
 
-To write JSON to a string, call [JsonSerializer.Serialize](xref:System.Text.Json.JsonSerializer.Serialize*), using a generic type parameter or generic type inference:
+To write JSON to a string, call the <xref:System.Text.Json.JsonSerializer.Serialize%2A?displayProperty=nameWithType> method. The following example uses an overload with a generic type parameter:
 
 ```csharp
+WeatherForecast weatherForecast;
+//...
 string json = JsonSerializer.Serialize<WeatherForecast>(weatherForecast);
 ```
 
+You can omit the generic type parameter and use generic type inference instead:
+
 ```csharp
-WeatherForecast weatherForecast = ... ;
+WeatherForecast weatherForecast;
 //...
 string json = JsonSerializer.Serialize(weatherForecast);
 ```
@@ -112,7 +118,7 @@ Overloads of <xref:System.Text.Json.JsonSerializer.Serialize%2A> let you seriali
 
 ### Serialize to UTF-8
 
-Call [JsonSerializer.SerializeToUtf8Bytes](xref:System.Text.Json.JsonSerializer.SerializeToUtf8Bytes*):
+To serialize to UTF-8, call the <xref:System.Text.Json.JsonSerializer.SerializeToUtf8Bytes%2A?displayProperty=nameWithType> method:
 
 ```csharp
 byte[] utf8Json = JsonSerializer.SerializeToUtf8Bytes<WeatherForecast>(weatherForecast);
@@ -122,29 +128,29 @@ As an alternative, a <xref:System.Text.Json.JsonSerializer.Serialize%2A> overloa
 
 Serializing to UTF-8 is about 5-10% faster than using the string-based methods. The difference is because the bytes (as UTF-8) don't need to be converted to strings (UTF-16).
 
-## Default serialization behavior
+## Serialization behavior
 
-* All public properties are serialized. You can [specify properties to exclude](#exclude-properties).
-* The [default encoder](xref:System.Text.Encodings.Web.JavaScriptEncoder.Default) escapes  non-ASCII characters, HTML-sensitive characters within the ASCII-range, and characters that must be escaped according to [the JSON spec](https://tools.ietf.org/html/rfc8259#section-7).
-* JSON is minified. You can optionally [pretty-print the JSON](#serialize-to-formatted-json).
-* Casing of JSON names matches the .NET names. You can [customize JSON name casing](#customize-json-names).
-* [Circular references](https://github.com/dotnet/corefx/issues/38579) are detected and exceptions thrown.
-* Fields are excluded.
+* By default, all public properties are serialized. You can [specify properties to exclude](#exclude-properties).
+* The [default encoder](xref:System.Text.Encodings.Web.JavaScriptEncoder.Default) escapes non-ASCII characters, HTML-sensitive characters within the ASCII-range, and characters that must be escaped according to [the JSON spec](https://tools.ietf.org/html/rfc8259#section-7).
+* By default, JSON is minified. You can [pretty-print the JSON](#serialize-to-formatted-json).
+* By default, casing of JSON names matches the .NET names. You can [customize JSON name casing](#customize-json-names).
+* Circular references are detected and exceptions thrown. For more information, see the [issue on circular references](https://github.com/dotnet/corefx/issues/38579) in the dotnet/corefx repository on GitHub.
+* Currently, fields are excluded.
 
 Supported types include:
 
-* .NET primitives that map to JavaScript primitives, such as numeric types, strings, and boolean.
+* .NET primitives that map to JavaScript primitives, such as numeric types, strings, and Boolean.
 * User-defined [Plain Old CLR Objects (POCOs)](https://stackoverflow.com/questions/250001/poco-definition).
 * One-dimensional and jagged arrays (`ArrayName[][]`).
 * `Dictionary<string,TValue>` where `TValue` is `object`, `JsonElement`, or a POCO.
-* [Collection types](https://github.com/dotnet/corefx/issues/36643) from the following namespaces:
+* Collections from the following namespaces. For more information, see the [issue on collection support](https://github.com/dotnet/corefx/issues/36643) in the dotnet/corefx repository on GitHub.
   * <xref:System.Collections>
   * <xref:System.Collections.Generic>
   * <xref:System.Collections.Immutable>
 
 ## How to read JSON into .NET objects (deserialize)
 
-To deserialize from a string, call [JsonSerializer.Deserialize](xref:System.Text.Json.JsonSerializer.Deserialize*):
+To deserialize from a string, call the <xref:System.Text.Json.JsonSerializer.Deserialize%2A?displayProperty=nameWithType> method, as shown in the following example:
 
 ```csharp
 string json = ... ;
@@ -158,36 +164,36 @@ Overloads of <xref:System.Text.Json.JsonSerializer.Deserialize*> let you deseria
 
 ### Deserialize from UTF-8
 
-Call a [JsonSerializer.Deserialize](xref:System.Text.Json.JsonSerializer.Deserialize*) overload that takes a `Utf8JsonReader` or a `ReadOnlySpan<byte>`:
+To deserialize from UTF-8, call a <xref:System.Text.Json.JsonSerializer.Deserialize%2A?displayProperty=nameWithType> overload that takes a `Utf8JsonReader` or a `ReadOnlySpan<byte>`, as shown in the following examples:
 
 ```csharp
-byte[] utf8Json = ... ;
-
+byte[] utf8Json;
+//...
 var readOnlySpan = new ReadOnlySpan<byte>(utf8Json);
 weatherForecast = JsonSerializer.Deserialize<WeatherForecastMin>(readOnlySpan);
 ```
 
 ```csharp
-byte[] utf8Json = ... ;
-
+byte[] utf8Json;
+//...
 var utf8Reader = new Utf8JsonReader(utf8Json);
 weatherForecast = JsonSerializer.Deserialize<WeatherForecastMin>(ref utf8Reader);
 ```
 
-## Default deserialization behavior
+## Deserialization behavior
 
-* Property name matching is case-sensitive. You can optionally specify [case-insensitivity](#case-insensitive-property-matching).
+* By default, property name matching is case-sensitive. You can [specify case-insensitivity](#case-insensitive-property-matching).
 * If the JSON contains a value for a read-only property, the value is ignored and no exception is thrown.
 * Deserialization to reference types without a parameterless constructor isn't supported.
-* Deserialization to [immutable objects](https://github.com/dotnet/corefx/issues/38569) or [read-only properties](https://github.com/dotnet/corefx/issues/38163) isn't supported.
-* Enums are supported as numbers.
+* Deserialization to immutable objects or read-only properties isn't supported. For more information, see the GitHub [issue on immutable object support](https://github.com/dotnet/corefx/issues/38569) and the [issue on read-only property support](https://github.com/dotnet/corefx/issues/38163) in the dotnet/corefx repository on GitHub.
+* By default, enums are supported as numbers.
 * Fields aren't supported.
-* Comments or trailing commas in the JSON throw exceptions. You can [allow comments and trailing commas](#allow-comments-and-trailing-commas).
+* By default, comments or trailing commas in the JSON throw exceptions. You can [allow comments and trailing commas](#allow-comments-and-trailing-commas) if needed.
 * The [default maximum depth](xref:System.Text.Json.JsonReaderOptions.MaxDepth) is 64.
 
 ## Serialize to formatted JSON
 
-Set <xref:System.Text.Json.JsonSerializerOptions.WriteIndented> to true:
+To pretty-print the JSON output, set <xref:System.Text.Json.JsonSerializerOptions.WriteIndented?displayProperty=nameWithType> to `true`:
 
 ```csharp
 var options = new JsonSerializerOptions
@@ -218,7 +224,7 @@ class WeatherForecast
 
 ## Allow comments and trailing commas
 
-Set <xref:System.Text.Json.JsonSerializerOptions.ReadCommentHandling> to `JsonCommentHandling.Skip`, and set <xref:System.Text.Json.JsonSerializerOptions.AllowTrailingCommas> to true:
+By default comments and trailing commas are not allowed in JSON. To allow comments in the JSON, set the <xref:System.Text.Json.JsonSerializerOptions.ReadCommentHandling?displayProperty=nameWithType> property to `JsonCommentHandling.Skip`. And to allow trailing commas, set the <xref:System.Text.Json.JsonSerializerOptions.AllowTrailingCommas?displayProperty=nameWithType> property to `true`. The following example shows how to allow both:
 
 ```csharp
 var options = new JsonSerializerOptions
@@ -241,14 +247,14 @@ Here's example JSON with comments and a trailing comma:
 
 ## Customize JSON names
 
-This section explains how to:
+By default, property names and dictionary keys are unchanged in the JSON output, including case. This section explains how to:
 
 * Customize individual property names
 * Convert all property names to camel case
 * Implement a custom property naming policy
 * Convert dictionary keys to camel case
 
-There's no support for automatically [converting enums to camel case](https://github.com/dotnet/corefx/issues/37725).
+Currently, there's no support for automatically converting enums to camel case. For more information, see the [issue on enum camel case support](https://github.com/dotnet/corefx/issues/37725) in the dotnet/corefx repository on GitHub.
 
 ### Customize individual property names
 
@@ -283,7 +289,7 @@ The property name set by this attribute:
 
 ### Use camel case for all JSON property names
 
-Set <xref:System.Text.Json.JsonSerializerOptions.PropertyNamingPolicy> to `JsonNamingPolicy.CamelCase`:
+To use camel case for all JSON property names, set <xref:System.Text.Json.JsonSerializerOptions.PropertyNamingPolicy?displayProperty=nameWithType> to `JsonNamingPolicy.CamelCase`, as shown in the following example:
 
 ```csharp
 var options = new JsonSerializerOptions
@@ -322,7 +328,7 @@ The camel case property naming policy:
 
 ### Use a custom JSON property naming policy
 
-Derive from <xref:System.Text.Json.JsonNamingPolicy> and override <xref:System.Text.Json.JsonNamingPolicy.ConvertName*>:
+To use a custom JSON property naming policy, create a class that derives from <xref:System.Text.Json.JsonNamingPolicy> and override the <xref:System.Text.Json.JsonNamingPolicy.ConvertName%2A> method, as shown in the following example:
 
 ```csharp
 class UpperCaseNamingPolicy : JsonNamingPolicy
@@ -334,7 +340,7 @@ class UpperCaseNamingPolicy : JsonNamingPolicy
 }
 ```
 
-Set <xref:System.Text.Json.JsonSerializerOptions.PropertyNamingPolicy> to an instance of your naming policy class:
+Then set the <xref:System.Text.Json.JsonSerializerOptions.PropertyNamingPolicy?displayProperty=nameWithType> property to an instance of your naming policy class:
 
 ```csharp
 var options = new JsonSerializerOptions
@@ -373,7 +379,7 @@ The JSON property naming policy:
 
 ### Camel case dictionary keys
 
-If a property of an object to be serialized is of type `Dictionary<string,Tvalue>`, the `string` keys can be converted to camel case. To do that, set <xref:System.Text.Json.JsonSerializerOptions.DictionaryKeyPolicy> to `JsonNamingPolicy.CamelCase`:
+If a property of an object to be serialized is of type `Dictionary<string,TValue>`, the `string` keys can be converted to camel case. To do that, set <xref:System.Text.Json.JsonSerializerOptions.DictionaryKeyPolicy> to `JsonNamingPolicy.CamelCase`, as shown in the following example:
 
 ```csharp
 var options = new JsonSerializerOptions
@@ -408,15 +414,15 @@ The camel case naming policy applies to serialization only.
 
 ## Exclude properties
 
-This section explains how to exclude:
+By default, all public properties are serialized. If you don't want some of them to appear in the JSON output, you have several options. This section explains how to exclude:
 
 * Individual properties
 * All read-only properties
 * All null-value properties 
 
 ### Exclude individual properties
 
-Use the [[JsonIgnore]](xref:System.Text.Json.Serialization.JsonIgnoreAttribute) attribute.
+To ignore individual properties, use the [[JsonIgnore]](xref:System.Text.Json.Serialization.JsonIgnoreAttribute) attribute.
 
 Here's an example type to serialize and JSON output:
 
@@ -441,7 +447,7 @@ class WeatherForecast
 
 ### Exclude all read-only properties
 
-Set <xref:System.Text.Json.JsonSerializerOptions.IgnoreReadOnlyProperties> to true:
+To exclude all read-only properties, set the <xref:System.Text.Json.JsonSerializerOptions.IgnoreReadOnlyProperties?displayProperty=nameWithType> to `true`, as shown in the following example:
 
 ```csharp
 var options = new JsonSerializerOptions
@@ -475,7 +481,7 @@ This option applies only to serialization. During deserialization, read-only pro
 
 ### Exclude all null value properties
 
-Set <xref:System.Text.Json.JsonSerializerOptions.IgnoreNullValues> to true:
+To exclude all null value properties, set the <xref:System.Text.Json.JsonSerializerOptions.IgnoreNullValues> property to `true`, as shown in the following example:
 
 ```csharp
 var options = new JsonSerializerOptions
@@ -500,11 +506,11 @@ Here's an example object to serialize and JSON output:
 }
 ```
 
-This setting applies to serialization and deserialization. During deserialization, null values in the JSON are ignored only if they are valid. [Null values for non-nullable value types cause exceptions](https://github.com/dotnet/corefx/issues/40922).
+This setting applies to serialization and deserialization. During deserialization, null values in the JSON are ignored only if they are valid. Null values for non-nullable value types cause exceptions. For more information, see the [issue on non-nullable value types](https://github.com/dotnet/corefx/issues/40922) in the dotnet/corefx repository on GitHub.
 
 ## Case-insensitive property matching
 
-By default, deserialization looks for case-sensitive property name matches between JSON and the target object properties. To change that behavior, set <xref:System.Text.Json.JsonSerializerOptions.PropertyNameCaseInsensitive> to true:
+By default, deserialization looks for case-sensitive property name matches between JSON and the target object properties. To change that behavior, set the <xref:System.Text.Json.JsonSerializerOptions.PropertyNameCaseInsensitive?displayProperty=nameWithType> to `true`:
 
 ```csharp
 var options = new JsonSerializerOptions
@@ -576,7 +582,7 @@ This behavior is intended to help prevent accidental exposure of data in a deriv
 
 To serialize the properties of the derived type, use one of the following approaches:
 
-* Call an overload of `Serialize` that lets you specify the type at runtime:
+* Call an overload of <xref:System.Text.Json.JsonSerializer.Serialize%2A> that lets you specify the type at runtime:
 
   ```csharp
   json = JsonSerializer.Serialize(weatherForecast, weatherForecast.GetType());
@@ -707,7 +713,12 @@ using (var stream = new MemoryStream())
 The following example shows how to use the <xref:System.Text.Json.Utf8JsonReader> class directly. The code assumes that the `jsonUtf8` variable is a byte array that contains valid JSON, encoded as UTF-8.
 
 ```csharp
-Utf8JsonReader reader = new Utf8JsonReader(jsonUtf8, isFinalBlock: true, state: default);
+var options = new JsonReaderOptions
+{
+    AllowTrailingCommas = true,
+    CommentHandling = JsonCommentHandling.Skip
+};
+Utf8JsonReader reader = new Utf8JsonReader(jsonUtf8, options);
 
 while (reader.Read())
 {

docs/standard/serialization/system-text-json-overview.md

@@ -1,6 +1,8 @@
 ---
 title: "JSON serialization in .NET"
-ms.date: "09/02/2019"
+author: tdykstra
+ms.author: tdykstra
+ms.date: "09/16/2019"
 helpviewer_keywords: 
   - "JSON serialization"
   - "serializing objects"