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
Next Next commit
add content for System.Text.Json from /// comments
  • Loading branch information
@mairaw
mairaw committed Feb 18, 2019
commit bd4ea8f2f3a0335a958951e82e3a39709354116f
8 changes: 4 additions & 4 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>To be added.</summary>
<summary>This enum defines the various ways the <see cref="T:System.Text.Json.Utf8JsonReader" /> can deal with comments.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -34,7 +34,7 @@
</ReturnValue>
<MemberValue>1</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Allow comments within the JSON input and treat them as a valid token. While reading, the caller will be able to access the comment values.</summary>
</Docs>
</Member>
<Member MemberName="Disallow">
Expand All @@ -54,7 +54,7 @@
</ReturnValue>
<MemberValue>0</MemberValue>
<Docs>
<summary>To be added.</summary>
<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>
</Docs>
</Member>
<Member MemberName="Skip">
Expand All @@ -74,7 +74,7 @@
</ReturnValue>
<MemberValue>2</MemberValue>
<Docs>
<summary>To be added.</summary>
<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>
</Docs>
</Member>
</Members>
Expand Down
25 changes: 14 additions & 11 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,7 +14,8 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</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 @@ -36,11 +37,13 @@
<Parameter Name="bytePositionInLine" Type="System.Int64" />
</Parameters>
<Docs>
<param name="message">To be added.</param>
<param name="lineNumber">To be added.</param>
<param name="bytePositionInLine">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="message">The context specific error message.</param>
<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>
</Docs>
</Member>
<Member MemberName="BytePositionInLine">
Expand All @@ -59,7 +62,7 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The number of bytes read within the current line before the exception (starting at 0).</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -84,9 +87,9 @@
<Parameter Name="context" Type="System.Runtime.Serialization.StreamingContext" />
</Parameters>
<Docs>
<param name="info">To be added.</param>
<param name="context">To be added.</param>
<summary>To be added.</summary>
<param name="info">The <see cref="T:System.Runtime.Serialization.SerializationInfo" /> that holds the serialized object data about the exception being thrown.</param>
<param name="context">The <see cref="T:System.Runtime.Serialization.StreamingContext" /> that contains contextual information about the source or destination.</param>
<summary>Sets the <see cref="T:System.Runtime.Serialization.SerializationInfo" /> with information about the exception.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -106,7 +109,7 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The number of lines read so far before the exception (starting at 0).</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down
5 changes: 3 additions & 2 deletions xml/System.Text.Json/JsonReaderOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -34,7 +35,7 @@
<ReturnType>System.Text.Json.JsonCommentHandling</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
Expand Down
30 changes: 21 additions & 9 deletions xml/System.Text.Json/JsonReaderState.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</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.Utf8JsonReader" /> to continue reading after processing incomplete data.
This type is required to support reentrancy when reading incomplete data, and to continue reading once more data is available. Unlike the <see cref="T:System.Text.Json.Utf8JsonReader" />, which is a ref struct,
this type 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" />.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -34,10 +36,19 @@
<Parameter Name="options" Type="System.Text.Json.JsonReaderOptions" />
</Parameters>
<Docs>
<param name="maxDepth">To be added.</param>
<param name="options">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<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>
<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>
<exception cref="T:System.ArgumentException">
Thrown when the max depth is set to a non-positive value (&lt;= 0)
</exception>
</Docs>
</Member>
<Member MemberName="BytesConsumed">
Expand All @@ -56,7 +67,7 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -77,7 +88,7 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -98,7 +109,7 @@
<ReturnType>System.Text.Json.JsonReaderOptions</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -119,7 +130,8 @@
<ReturnType>System.SequencePosition</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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
with a ReadOnlySpan&lt;byte&gt; instead, this will always return a default <see cref="T:System.SequencePosition" />.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down
4 changes: 3 additions & 1 deletion xml/System.Text.Json/JsonTokenType.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,9 @@
<BaseTypeName>System.Enum</BaseTypeName>
</Base>
<Docs>
<summary>To be added.</summary>
<summary>This enum defines the various JSON tokens that make up a JSON text and is used by the <see cref="T:System.Text.Json.Utf8JsonReader" /> when moving from one token to the next.
The <see cref="T:System.Text.Json.Utf8JsonReader" /> starts at 'None' by default. The 'Comment' enum value is only ever reached in a specific <see cref="T:System.Text.Json.Utf8JsonReader" /> mode and is not
reachable by default.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down
21 changes: 17 additions & 4 deletions xml/System.Text.Json/JsonWriterOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Provides the ability for the user to define custom behavior when writing JSON
using the <see cref="T:System.Text.Json.Utf8JsonWriter" />. By default, the JSON is written without
any indentation or extra white space. Also, the <see cref="T:System.Text.Json.Utf8JsonWriter" /> will
throw an exception if the user attempts to write structurally invalid JSON.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -34,7 +37,9 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Defines whether the <see cref="T:System.Text.Json.Utf8JsonWriter" /> should pretty print the JSON which includes:
indenting nested JSON tokens, adding new lines, and adding white space between property names and values.
By default, the JSON is written without any extra white space.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -55,9 +60,17 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Defines whether the <see cref="T:System.Text.Json.Utf8JsonWriter" /> should skip structural validation and allow
the user to write invalid JSON, when set to true. If set to false, any attempts to write invalid JSON will result in
a <exception cref="T:System.InvalidOperationException" /> to be thrown.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>
If the JSON being written is known to be correct,
then skipping validation (by setting it to true) could improve performance.
An example of invalid JSON where the writer will throw (when SkipValidation
is set to false) is when you write a value within a JSON object
without a property name.
</remarks>
</Docs>
</Member>
</Members>
Expand Down
33 changes: 25 additions & 8 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,8 +14,14 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<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>
<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 @@ -33,9 +39,16 @@
<Parameter Name="options" Type="System.Text.Json.JsonWriterOptions" />
</Parameters>
<Docs>
<param name="options">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<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>
<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" />.
</remarks>
</Docs>
</Member>
<Member MemberName="BytesCommitted">
Expand All @@ -54,7 +67,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -75,7 +89,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -96,7 +111,9 @@
<ReturnType>System.Text.Json.JsonWriterOptions</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the custom behavior when writing JSON using
the <see cref="T:System.Text.Json.Utf8JsonWriter" /> which indicates whether to format the output
while writing and whether to skip structural JSON validation or not.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down
Loading