Skip to content

Port System.Text.Json source comments to Docs (second attempt) #2471

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 3 commits into from
May 29, 2019
Merged

Port System.Text.Json source comments to Docs (second attempt) #2471

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
90f9185
Port System.Text.Json source code comments to Docs - second attempt w…
carlossanlop May 20, 2019
aecf3f1
Incorporated revisions
May 22, 2019
1b19c68
Additional change
May 22, 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
179 changes: 139 additions & 40 deletions xml/System.Text.Json/JsonDocument.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,14 @@
</Interface>
</Interfaces>
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<summary>Provides a mechanism for examining the structural content of a JSON value without automatically instantiating data values.</summary>
<remarks>
<format><![CDATA[

This class utilizes resources from pooled memory to minimize the impact of the garbage collector (GC) in high-usage scenarios. Failure to properly dispose this object will result in the memory not being returned to the pool, which will increase GC impact across various parts of the framework.

]]></format>
</remarks>
</Docs>
<Members>
<Member MemberName="Dispose">
Expand Down Expand Up @@ -65,11 +71,25 @@
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
</Parameters>
<Docs>
<param name="utf8Json">To be added.</param>
<param name="readerOptions">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="utf8Json">The JSON text to parse.</param>
<param name="readerOptions">Options to control the reader behavior during parsing.</param>
<summary>Parses a sequence as UTF-8-encoded text representing a single JSON byte value into a JsonDocument.</summary>
<returns>A JsonDocument representation of the JSON value.</returns>
<remarks>
<format><![CDATA[

The <xref:T:System.Buffers.ReadOnlySequence`1> may be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime.

Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must not be present.

]]></format>
</remarks>
<exception cref="T:System.Text.Json.JsonException">
<paramref name="utf8Json" /> does not represent a valid single JSON value.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="readerOptions" /> contains unsupported options.
</exception>
</Docs>
</Member>
<Member MemberName="Parse">
Expand All @@ -91,11 +111,17 @@
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
</Parameters>
<Docs>
<param name="utf8Json">To be added.</param>
<param name="readerOptions">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="utf8Json">The JSON data to parse.</param>
<param name="readerOptions">Options to control the reader behavior during parsing.</param>
<summary>Parses a <see cref="T:System.IO.Stream" /> as UTF-8-encoded data representing a single JSON value into a JsonDocument. The stream is read to completion.</summary>
<returns>A JsonDocument representation of the JSON value.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.Text.Json.JsonException">
<paramref name="utf8Json" /> does not represent a valid single JSON value.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="readerOptions" /> contains unsupported options.
</exception>
</Docs>
</Member>
<Member MemberName="Parse">
Expand All @@ -117,11 +143,25 @@
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
</Parameters>
<Docs>
<param name="utf8Json">To be added.</param>
<param name="readerOptions">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="utf8Json">The JSON text to parse.</param>
<param name="readerOptions">Options to control the reader behavior during parsing.</param>
<summary>Parses memory as UTF-8-encoded text representing a single JSON byte value into a JsonDocument.</summary>
<returns>A JsonDocument representation of the JSON value.</returns>
<remarks>
<format><![CDATA[

The <xref:T:System.ReadOnlyMemory`1> value will be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime.

Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must not be present.

]]></format>
</remarks>
<exception cref="T:System.Text.Json.JsonException">
<paramref name="utf8Json" /> does not represent a valid single JSON value.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="readerOptions" /> contains unsupported options.
</exception>
</Docs>
</Member>
<Member MemberName="Parse">
Expand All @@ -143,11 +183,23 @@
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
</Parameters>
<Docs>
<param name="json">To be added.</param>
<param name="readerOptions">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="json">The JSON text to parse.</param>
<param name="readerOptions">Options to control the reader behavior during parsing.</param>
<summary>Parses text representing a single JSON character value into a JsonDocument.</summary>
<returns>A JsonDocument representation of the JSON value.</returns>
<remarks>
<format><![CDATA[

The <xref:T:System.ReadOnlyMemory`1> value may be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime.

]]></format>
</remarks>
<exception cref="T:System.Text.Json.JsonException">
<paramref name="json" /> does not represent a valid single JSON value.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="readerOptions" /> contains unsupported options.
</exception>
</Docs>
</Member>
<Member MemberName="Parse">
Expand All @@ -169,11 +221,17 @@
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
</Parameters>
<Docs>
<param name="json">To be added.</param>
<param name="readerOptions">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="json">The JSON text to parse.</param>
<param name="readerOptions">Options to control the reader behavior during parsing.</param>
<summary>Parses text representing a single JSON string value into a JsonDocument.</summary>
<returns>A JsonDocument representation of the JSON value.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.Text.Json.JsonException">
<paramref name="json" /> does not represent a valid single JSON value.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="readerOptions" /> contains unsupported options.
</exception>
</Docs>
</Member>
<Member MemberName="ParseAsync">
Expand All @@ -195,12 +253,18 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
</Parameters>
<Docs>
<param name="utf8Json">To be added.</param>
<param name="readerOptions">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="utf8Json">The JSON data to parse.</param>
<param name="readerOptions">Options to control the reader behavior during parsing.</param>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<summary>Parses a <see cref="T:System.IO.Stream" /> as UTF-8-encoded data representing a single JSON value into a JsonDocument. The stream is read to completion.</summary>
<returns>A task to produce a JsonDocument representation of the JSON value.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.Text.Json.JsonException">
<paramref name="utf8Json" /> does not represent a valid single JSON value.
</exception>
<exception cref="T:System.ArgumentException">
<paramref name="readerOptions" /> contains unsupported options.
</exception>
</Docs>
</Member>
<Member MemberName="ParseValue">
Expand All @@ -222,10 +286,27 @@
<Parameter Name="reader" Type="System.Text.Json.Utf8JsonReader" RefType="ref" />
</Parameters>
<Docs>
<param name="reader">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="reader">The reader to read.</param>
<summary>Parses one JSON value (including objects or arrays) from the provided reader.</summary>
<returns>A JsonDocument representing the value (and nested values) read from the reader.</returns>
<remarks>
<format><![CDATA[

If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of `reader` is <xref:System.Text.Json.JsonTokenType.PropertyName> or <xref:System.Text.Json.JsonTokenType.None?displayProperty=nameWithType>, the reader will advance by one call to <xref:System.Text.Json.Utf8JsonReader.Read?displayProperty=nameWithType> to determine the start of the value.

Upon completion of this method, `reader` is positioned at the final token in the JSON value. If an exception is thrown, the reader is reset to
the state it was in when the method was called.

This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="reader" /> contains unsupported options.
</exception>
<exception cref="T:System.Text.Json.JsonException">
A value could not be read from the reader.
</exception>
</Docs>
</Member>
<Member MemberName="RootElement">
Expand All @@ -244,7 +325,7 @@
<ReturnType>System.Text.Json.JsonElement</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the root element of this JSON document.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -269,11 +350,29 @@
<Parameter Name="document" Type="System.Text.Json.JsonDocument" RefType="out" />
</Parameters>
<Docs>
<param name="reader">To be added.</param>
<param name="document">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="reader">The reader to read.</param>
<param name="document">When the method returns, contains the parsed document.</param>
<summary>Attempts to parse one JSON value (including objects or arrays) from the provided reader.</summary>
<returns>
<see langword="true" /> if a value was read and parsed into a JsonDocument; <see langword="false" /> if the reader ran out of data while parsing. All other situations result in an exception being thrown.</returns>
<remarks>
<format><![CDATA[

If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of `reader` is <xref:System.Text.Json.JsonTokenType.PropertyName?displayProperty=nameWithType> or <xref:System.Text.Json.JsonTokenType.None?displayProperty=nameWithType>, the reader will advance by one call to <xref:System.Text.Json.Utf8JsonReader.Read?displayProperty=nameWithType> to determine the start of the value.

Upon completion of this method, `reader` is positioned at the final token in the JSON value. If an exception is thrown or `false`
is returned, the reader is reset to the state it was in when the method was called.

This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="reader" /> contains unsupported options.
</exception>
<exception cref="T:System.Text.Json.JsonException">
A value could not be read from the reader.
</exception>
</Docs>
</Member>
</Members>
Expand Down
6 changes: 3 additions & 3 deletions xml/System.Text.Json/JsonElement+ArrayEnumerator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
</Interface>
</Interfaces>
<Docs>
<summary>To be added.</summary>
<summary>Represents an enumerator for the contents of a JSON array.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down Expand Up @@ -99,8 +99,8 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Returns an enumerator that iterates through a collection.</summary>
<returns>An enumeratore that can be used to iterate through the array.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
14 changes: 10 additions & 4 deletions xml/System.Text.Json/JsonElement+ObjectEnumerator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
</Interface>
</Interfaces>
<Docs>
<summary>To be added.</summary>
<summary>Represents an enumerator for the properties of a JSON object.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down Expand Up @@ -99,9 +99,15 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Returns an enumerator that iterates the properties of an object.</summary>
<returns>An enumerator that can be used to iterate through the object.</returns>
<remarks>
<format><![CDATA[

The enumerator will enumerate the properties in the order they are declared, and when an object has multiple definitions of a single property, they will all individually be returned (each in the order they appear in the content).

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="MoveNext">
Expand Down
Loading