Skip to content

add content for System.Text.Json APIs #1880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Apr 11, 2019
Merged

add content for System.Text.Json APIs #1880

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
bd4ea8f
add content for System.Text.Json from /// comments
mairaw Feb 18, 2019
ba46946
edit pass + formatting
mairaw Feb 18, 2019
54e4a0b
save interim changes
mairaw Mar 9, 2019
4874aa0
Merge branch 'master' into system.text.json
mairaw Apr 5, 2019
bff4e25
feedback
mairaw Apr 5, 2019
6a0a9f1
last edits
mairaw Apr 9, 2019
c9360c3
Apply suggestions from peer review
mairaw Apr 11, 2019
a8d0713
Merge branch 'master' into system.text.json
mairaw Apr 11, 2019
e73cf6f
feedback
mairaw Apr 11, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
edit pass + formatting
  • Loading branch information
@mairaw
mairaw committed Feb 20, 2019
commit ba469465ff12d9b2963d5c41fc3f60b6b080a922
6 changes: 3 additions & 3 deletions xml/System.Text.Json/JsonCommentHandling.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<BaseTypeName>System.Enum</BaseTypeName>
</Base>
<Docs>
<summary>This enum defines the various ways the <see cref="T:System.Text.Json.Utf8JsonReader" /> can deal with comments.</summary>
<summary>Defines the different ways the <see cref="T:System.Text.Json.Utf8JsonReader" /> object handles comments.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down Expand Up @@ -54,7 +54,7 @@
</ReturnValue>
<MemberValue>0</MemberValue>
<Docs>
<summary>By default, do no allow comments within the JSON input. Comments are treated as invalid JSON if found and a <see cref="T:System.Text.Json.JsonReaderException" /> is thrown.</summary>
<summary>Doesn't allow comments within the JSON input. Comments are treated as invalid JSON if found and a <see cref="T:System.Text.Json.JsonReaderException" /> is thrown. This is the default value.</summary>
</Docs>
</Member>
<Member MemberName="Skip">
Expand All @@ -74,7 +74,7 @@
</ReturnValue>
<MemberValue>2</MemberValue>
<Docs>
<summary>Allow comments within the JSON input and ignore them. The <see cref="T:System.Text.Json.Utf8JsonReader" /> will behave as if no comments were present.</summary>
<summary>Allows comments within the JSON input and ignore them. The <see cref="T:System.Text.Json.Utf8JsonReader" /> behaves as if no comments are present.</summary>
</Docs>
</Member>
</Members>
Expand Down
15 changes: 6 additions & 9 deletions xml/System.Text.Json/JsonReaderException.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,7 @@
</Base>
<Interfaces />
<Docs>
<summary>Defines a custom exception object that is thrown by the <see cref="T:System.Text.Json.Utf8JsonReader" /> whenever it encounters an invalid JSON text while reading through it. This exception is also thrown
whenever you read past the defined maximum depth.</summary>
<summary>Defines a custom exception object that is thrown by the <see cref="T:System.Text.Json.Utf8JsonReader" /> whenever it encounters an invalid JSON text while reading through it. This exception is also thrown whenever you read past the defined maximum depth.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -41,9 +40,7 @@
<param name="lineNumber">The line number at which the invalid JSON was encountered (starting at 0).</param>
<param name="bytePositionInLine">The byte count within the current line where the invalid JSON was encountered (starting at 0).</param>
<summary>Creates a new exception object to relay error information to the user.</summary>
<remarks>
Note that the <paramref name="bytePositionInLine" /> counts the number of bytes (i.e. UTF-8 code units) and not characters or scalars.
</remarks>
<remarks>Note that the <paramref name="bytePositionInLine" /> counts the number of bytes (that is, UTF-8 code units) and not characters or scalars.</remarks>
</Docs>
</Member>
<Member MemberName="BytePositionInLine">
Expand All @@ -62,8 +59,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>The number of bytes read within the current line before the exception (starting at 0).</summary>
<value>To be added.</value>
<summary>Gets the number of bytes read within the current line before the exception (starting at 0).</summary>
<value>The number of bytes read within the current line before the exception (starting at 0).</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -109,8 +106,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>The number of lines read so far before the exception (starting at 0).</summary>
<value>To be added.</value>
<summary>Gets the number of lines read so far before the exception (starting at 0).</summary>
<value>The number of lines read so far before the exception (starting at 0).</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
6 changes: 3 additions & 3 deletions xml/System.Text.Json/JsonReaderOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
<Interfaces />
<Docs>
<summary>Provides the ability for the user to define custom behavior when reading JSON using the <see cref="T:System.Text.Json.Utf8JsonReader" /> that may deviate from strict adherence
to the JSON specification (as per the JSON RFC - https://tools.ietf.org/html/rfc8259), which is the default behavior.</summary>
to the JSON specification (as per the <see href="https://tools.ietf.org/html/rfc8259">JSON RFC</see>), which is the default behavior.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -35,8 +35,8 @@
<ReturnType>System.Text.Json.JsonCommentHandling</ReturnType>
</ReturnValue>
<Docs>
<summary>Defines how the <see cref="T:System.Text.Json.Utf8JsonReader" /> should handle comments when reading through the JSON.</summary>
<value>To be added.</value>
<summary>Gets or sets how the <see cref="T:System.Text.Json.Utf8JsonReader" /> object handles comments when reading through the JSON data.</summary>
<value>One of the enumeration values that indicates how comments are handled.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
35 changes: 16 additions & 19 deletions xml/System.Text.Json/JsonReaderState.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,19 +36,16 @@
<Parameter Name="options" Type="System.Text.Json.JsonReaderOptions" />
</Parameters>
<Docs>
<param name="maxDepth">Sets the maximum depth allowed when reading JSON, with the default set as 64. Reading past this depth will throw a <exception cref="T:System.Text.Json.JsonReaderException" />.</param>
<param name="options">Defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonReader" /> that is different from the JSON RFC (for example how to handle comments).
By default, the <see cref="T:System.Text.Json.Utf8JsonReader" /> follows the JSON RFC strictly (i.e. comments within the JSON are invalid).</param>
<summary>Constructs a new <see cref="T:System.Text.Json.JsonReaderState" /> instance.</summary>
<param name="maxDepth">The maximum depth allowed when reading JSON. This is an optional parameter and its default value is 64. Reading past this depth throws a <exception cref="T:System.Text.Json.JsonReaderException" /></param>
<param name="options">The customized behavior of the <see cref="T:System.Text.Json.Utf8JsonReader" /> that is different from the JSON RFC (for example, how to handle comments).
This is an optional parameter and by default, the <see cref="T:System.Text.Json.Utf8JsonReader" /> object follows the JSON RFC strictly (that is, comments within the JSON are invalid).</param>
<summary>Initializes a new instance of the <see cref="T:System.Text.Json.JsonReaderState" /> class.</summary>
<remarks>
An instance of this state must be passed to the <see cref="T:System.Text.Json.Utf8JsonReader" /> ctor with the JSON data.
Unlike the <see cref="T:System.Text.Json.Utf8JsonReader" />, which is a ref struct, the state can survive
across async/await boundaries and hence this type is required to provide support for reading
in more data asynchronously before continuing with a new instance of the <see cref="T:System.Text.Json.Utf8JsonReader" />.
</remarks>
An instance of this state must be passed to the <see cref="T:System.Text.Json.Utf8JsonReader" /> constructor with the JSON data.
Unlike the <see cref="T:System.Text.Json.Utf8JsonReader" />, which is a ref struct, the state can survive across async/await boundaries and hence this type is required to provide support for reading in more data asynchronously before continuing with a new instance of the <see cref="T:System.Text.Json.Utf8JsonReader" /> class.
</remarks>
<exception cref="T:System.ArgumentException">
Thrown when the max depth is set to a non-positive value (&lt;= 0)
</exception>
<paramref name="maxDepth" /> is less than or equal to 0.</exception>
</Docs>
</Member>
<Member MemberName="BytesConsumed">
Expand All @@ -67,8 +64,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>Returns the total amount of bytes consumed by the <see cref="T:System.Text.Json.Utf8JsonReader" /> so far for the given UTF-8 encoded input text.</summary>
<value>To be added.</value>
<summary>Gets the total amount of bytes consumed by the <see cref="T:System.Text.Json.Utf8JsonReader" /> so far for the given UTF-8 encoded input text.</summary>
<value>The total amount of bytes consumed by the <see cref="T:System.Text.Json.Utf8JsonReader" /> so far.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -88,9 +85,9 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets the maximum depth allowed when reading JSON. Reading past this depth will throw a <exception cref="T:System.Text.Json.JsonReaderException" />.</summary>
<summary>Gets the maximum depth allowed when reading JSON.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>Reading past this depth throws a <exception cref="T:System.Text.Json.JsonReaderException" />.</remarks>
</Docs>
</Member>
<Member MemberName="Options">
Expand All @@ -109,8 +106,8 @@
<ReturnType>System.Text.Json.JsonReaderOptions</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the custom behavior when reading JSON using the <see cref="T:System.Text.Json.Utf8JsonReader" /> that may deviate from strict adherence to the JSON specification, which is the default behavior.</summary>
<value>To be added.</value>
<summary>Gets the custom behavior to use when reading JSON data using the <see cref="T:System.Text.Json.Utf8JsonReader" /> object that may deviate from strict adherence to the JSON specification, which is the default behavior.</summary>
<value>The custom behavior to use when reading JSON data.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -130,9 +127,9 @@
<ReturnType>System.SequencePosition</ReturnType>
</ReturnValue>
<Docs>
<summary>Returns the current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt;. If the <see cref="T:System.Text.Json.Utf8JsonReader" /> was constructed
<summary>Gets the current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt;. If the <see cref="T:System.Text.Json.Utf8JsonReader" /> object was constructed
with a ReadOnlySpan&lt;byte&gt; instead, this will always return a default <see cref="T:System.SequencePosition" />.</summary>
<value>To be added.</value>
<value>The current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt;.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
40 changes: 16 additions & 24 deletions xml/System.Text.Json/JsonWriterState.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,11 @@
</Base>
<Interfaces />
<Docs>
<summary>Defines an opaque type that holds and saves all the relevant state information which must be provided
to the <see cref="T:System.Text.Json.Utf8JsonWriter" /> to continue writing after completing a partial write.</summary>
<summary>Defines an opaque type that holds and saves all the relevant state information which must be provided to the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object to continue writing after completing a partial write.</summary>
<remarks>
This type is required to support reentrancy when writing incomplete data, and to continue
writing in chunks. Unlike the <see cref="T:System.Text.Json.Utf8JsonWriter" />, which is a ref struct,
this type can survive across async/await boundaries and hence this type is required to provide
support for writing more JSON text asynchronously before continuing with a new instance of the <see cref="T:System.Text.Json.Utf8JsonWriter" />.
</remarks>
This type is required to support reentrancy when writing incomplete data, and to continue writing in chunks. Unlike the <see cref="T:System.Text.Json.Utf8JsonWriter" />, which is a ref struct,
this type can survive across async/await boundaries and hence this type is required to provide support for writing more JSON text asynchronously before continuing with a new instance of the <see cref="T:System.Text.Json.Utf8JsonWriter" />.
</remarks>
</Docs>
<Members>
<Member MemberName=".ctor">
Expand All @@ -39,15 +36,13 @@
<Parameter Name="options" Type="System.Text.Json.JsonWriterOptions" />
</Parameters>
<Docs>
<param name="options">Defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" />
By default, the <see cref="T:System.Text.Json.Utf8JsonWriter" /> writes JSON minimized (i.e. with no extra whitespace)
and validates that the JSON being written is structurally valid according to JSON RFC.</param>
<summary>Constructs a new <see cref="T:System.Text.Json.JsonWriterState" /> instance.</summary>
<param name="options">The customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object.
By default, the <see cref="T:System.Text.Json.Utf8JsonWriter" /> writes JSON minimized (that is, with no extra whitespace) and validates that the JSON data being written is structurally valid according to JSON RFC.</param>
<summary>Initializes a new instance of the <see cref="T:System.Text.Json.JsonWriterState" /> class.</summary>
<remarks>
An instance of this state must be passed to the <see cref="T:System.Text.Json.Utf8JsonWriter" /> ctor with the output destination.
Unlike the <see cref="T:System.Text.Json.Utf8JsonWriter" />, which is a ref struct, the state can survive
across async/await boundaries and hence this type is required to provide support for reading
in more data asynchronously before continuing with a new instance of the <see cref="T:System.Text.Json.Utf8JsonWriter" />.
An instance of this state must be passed to the <see cref="T:System.Text.Json.Utf8JsonWriter" /> constructor with the output destination.
Unlike the <see cref="T:System.Text.Json.Utf8JsonWriter" />, which is a ref struct, the state can survive across async/await boundaries and hence this type is required to provide support for reading
in more data asynchronously before continuing with a new instance of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object.
</remarks>
</Docs>
</Member>
Expand All @@ -67,9 +62,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>Returns the total amount of bytes committed to the output by the <see cref="T:System.Text.Json.Utf8JsonWriter" /> so far.
This is how much the IBufferWriter has advanced.</summary>
<value>To be added.</value>
<summary>Gets the total amount of bytes committed to the output by the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object so far. This indicates how much the <see cref="T:System.Buffers.IBufferWriter`1" /> has advanced.</summary>
<value>The total amount of bytes committed to the output.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -89,9 +83,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>Returns the total amount of bytes written by the <see cref="T:System.Text.Json.Utf8JsonWriter" /> so far.
This includes data that has been written beyond what has already been committed.</summary>
<value>To be added.</value>
<summary>Gets the total amount of bytes written by the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object so far. This includes data that has been written beyond what has already been committed.</summary>
<value>The total amount of bytes written.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -111,10 +104,9 @@
<ReturnType>System.Text.Json.JsonWriterOptions</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the custom behavior when writing JSON using
the <see cref="T:System.Text.Json.Utf8JsonWriter" /> which indicates whether to format the output
<summary>Gets the custom behavior to use when writing JSON data using the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object, which indicates whether to format the output
while writing and whether to skip structural JSON validation or not.</summary>
<value>To be added.</value>
<value>The custom behavior to use when writing JSON data.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
Loading