-Documentation

2015-06-10 01:16:12 +12:00
parent f4e8c3d2ca
commit 08296c5eca
12 changed files with 120 additions and 16 deletions
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<topic id="JsonConstructorAttribute" revisionNumber="1">
+  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <introduction>
+      <para>This sample uses the
+      <codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference>
+      to specify that a constrctor should be used to create a class during deserialization.</para>
+    </introduction>
+    <section>
+      <title>Sample</title>
+      <content>
+        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Types" title="Types" />
+        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Usage" title="Usage" />
+      </content>
+    </section>
+  </developerConceptualDocument>
+</topic>
@@ -16,10 +16,8 @@
        <para>SelectToken is a method on JToken and takes a string path to a child token.
        SelectToken returns the child token or a null reference if a token couldn't be
        found at the path's location.</para>
-        <para>The path is made up of property names and array indexes separated by periods.
-        Array indexes can use either square or round brackets. Both of the following are
-        valid paths and are equivalent to each other: <codeInline>Manufacturers[0].Name</codeInline>
-        and <codeInline>Manufacturers(0).Name</codeInline>.</para>
+        <para>The path is made up of property names and array indexes separated by periods,
+        e.g. <codeInline>Manufacturers[0].Name</codeInline>.</para>

 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="SelectTokenComplex" title="SelectToken Example" />
      </content>
@@ -12,6 +12,7 @@
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference> - Placed on fields and properties to control how they should be serialized as a property in a JSON object.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference> - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonExtensionDataAttribute</codeEntityReference> - Placed on a collection field or property to deserialize properties with no matching class member into the specified collection and write values during serialization.</para></listItem>
+  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference> - Placed on a constructor to specify that it should be used to create the class during deserialization.</para></listItem>
 </list>

    </introduction>
@@ -99,12 +100,10 @@
        on a field or property, then the specified JsonConverter will always be used to serialize that value.</para>
        <para>The priority of which JsonConverter is used is member attribute, then class attribute, and finally
        any converters passed to the JsonSerializer.</para>
-        
- <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksObject" title="JsonConverter Attribute" />
+
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConverterAttributeProperty.cs" region="Types" title="JsonConverterAttribute Property Example" />
       
        <para>This example shows the JsonConverterAttribute being applied to a property.</para>
-        
-<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksExample" title="JsonConverter Example" />
                
        <para>To apply a JsonConverter to the items in a collection, use either <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>,
        <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> or
@@ -124,6 +123,16 @@
        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\DeserializeExtensionData.cs" region="Usage" title="Usage" />
      </content>
    </section>
+        
+    <section>
+      <title>JsonConstructorAttribute</title>
+      <content>
+        <para>The <codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference> instructs the
+        <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference> to use a specific constructor when deserializing a class. It can be used to create a class using a parameterized constructor instead of the default constructor, or to pick which specific parameterized constructor to use if there are multiple.</para>
+        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Types" title="Types" />
+        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Usage" title="Usage" />
+      </content>
+    </section>
    
    </sections>
    </section>
@@ -30,7 +30,7 @@
  <Topic id="JsonNetVsDotNetSerializers" visible="True" title="Json.NET vs .NET Serializers" />
  <Topic id="JsonNetVsWindowsDataJson" visible="True" title="Json.NET vs Windows.Data.Json" />
  <Topic id="Samples" visible="True" isExpanded="true" title="Samples">
-    <Topic id="d6e185d5-c992-44fc-8d8f-d9acc2bbec2f" visible="True" noFile="true" title="Serializing JSON">
+    <Topic id="d6e185d5-c992-44fc-8d8f-d9acc2bbec2f" visible="True" noFile="true" isExpanded="true" title="Serializing JSON">
      <Topic id="SerializeObject" visible="True" title="Serialize an Object" />
      <Topic id="SerializeCollection" visible="True" title="Serialize a Collection" />
      <Topic id="SerializeDictionary" visible="True" title="Serialize a Dictionary" />
@@ -67,6 +67,7 @@
      <Topic id="CustomContractResolver" visible="True" title="Custom IContractResolver" />
      <Topic id="CustomTraceWriter" visible="True" title="Custom ITraceWriter" />
      <Topic id="SerializeSerializationBinder" visible="True" title="Custom SerializationBinder" />
+      <Topic id="JsonConstructorAttribute" visible="True" isSelected="true" />
      <Topic id="JsonConverterAttributeClass" visible="True" title="JsonConverterAttribute on a class" />
      <Topic id="JsonConverterAttributeProperty" visible="True" title="JsonConverterAttribute on a property" />
      <Topic id="JsonObjectAttributeOptIn" visible="True" title="JsonObjectAttribute opt-in serialization" />
@@ -153,7 +154,7 @@
    <Topic id="ca145ed0-f377-4f1c-9479-d1629082fc6e" visible="True" noFile="true" isExpanded="true" title="Reading and Writing JSON">
      <Topic id="ReadJsonWithJsonTextReader" visible="True" title="Read JSON with JsonTextReader" />
      <Topic id="WriteJsonWithJsonTextWriter" visible="True" title="Write JSON with JsonTextWriter" />
-      <Topic id="ReadMultipleContentWithJsonReader" visible="True" isSelected="true" title="Read Multiple Fragments With JsonReader" />
+      <Topic id="ReadMultipleContentWithJsonReader" visible="True" title="Read Multiple Fragments With JsonReader" />
      <Topic id="CustomJsonReader" visible="True" title="Custom JsonReader" />
      <Topic id="CustomJsonWriter" visible="True" title="Custom JsonWriter" />
    </Topic>
@@ -100,6 +100,7 @@
  </ItemGroup>
  <ItemGroup>
    <Content Include="icons\favicon.ico" />
+    <None Include="Samples\Serializer\JsonConstructorAttribute.aml" />
    <None Include="Samples\Json\ReadMultipleContentWithJsonReader.aml" />
    <None Include="Samples\Serializer\SerializeImmutableCollections.aml" />
    <None Include="Samples\Serializer\SerializeExtensionData.aml" />