add content for System.Text.Json APIs #1880
Conversation
mairaw
added
the
🏁 Release: .NET Core 3.0
mairaw
changed the title
mairaw
force-pushed
the
system.text.json
branch
2 times, most recently
from
5075c29 to
523d5dd
Compare
mairaw
force-pushed
the
system.text.json
branch
from
523d5dd to
ba46946
Compare
|
This is still WIP. I should have made that clear earlier but wanted to make sure you saw I was loading the comments you wanted. |
Sounds good, thanks for letting me know :) |
| ]]></format> | ||
| </remarks> | ||
| <exception cref="T:System.InvalidOperationException"> | ||
| The JSON token value isn't a <see cref="F:System.Text.Json.JsonTokenType.Number" />.</exception> |
There was a problem hiding this comment.
Should all of these InvalidOperationException messages use the more-Englishy The JSON token value isn't <see cref="Number"/> or the more programmery <see cref="TokenType" /> is not <see cref="Number" />?
There was a problem hiding this comment.
It renders like this:
i think it's fine as-is?
|
@ahsonkhan @bartonjs thanks so much for your feedback! I believe I've addressed everything and I had some last questions before we can merge this. |
mairaw
changed the title
| <Interfaces /> | ||
| <Docs> | ||
| <summary>To be added.</summary> | ||
| <summary>Provides the ability for the user to define custom behavior when reading JSON.</summary> |
There was a problem hiding this comment.
Is the intention that this would be merged for preview3? I am asking because in the upcoming preview4 build, we moved MaxDepth to JsonReaderOptions (from JsonReaderState here: https://github.com/dotnet/dotnet-api-docs/pull/1880/files#diff-e0eccf9b88a4e527eed98ff46094dbdbR39).
There was a problem hiding this comment.
Yes, that's my intention 😄
| <value>To be added.</value> | ||
| <remarks>To be added.</remarks> | ||
| <summary>Gets or sets a value that indicates whether the <see cref="T:System.Text.Json.Utf8JsonWriter" /> should skip structural validation and allow the user to write invalid JSON.</summary> | ||
| <value><see langword="true" /> to skip structural validation and allow invalid JSON; otherwise, <see langword="false" />: any attempts to write invalid JSON will result in |
There was a problem hiding this comment.
Is using : correct here? Can you share the link to the docs so I can see how it would look?
There was a problem hiding this comment.
I'm not totally happy with this description. I'll see if I can improve this a bit.
Co-Authored-By: mairaw <[email protected]>
|
Thank you all for your feedback. I think I've handled all the comments I got. If everything looks good, we can merge tomorrow. |
| <summary>To be added.</summary> | ||
| <remarks>To be added.</remarks> | ||
| <param name="bufferWriter">An instance of <see cref="T:System.Buffers.IBufferWriter`1" /> used as a destination for writing JSON text.</param> | ||
| <param name="state">A struct that contains the reader state. On the first call to the constructor, it should reflect a default state; otherwise, it should capture the state from the previous instance instance of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> and pass that back.</param> |
There was a problem hiding this comment.
writer state, not reader state.
There was a problem hiding this comment.
On the first call to the constructor, it should reflect a default state
I don't think that captures the intent. The state is being passed in to the ctor. Why is it reflecting anything?
it should capture the state from the previous instance instance of the
Not "it", the caller should capture the state...
| <remarks>To be added.</remarks> | ||
| <param name="bufferWriter">An instance of <see cref="T:System.Buffers.IBufferWriter`1" /> used as a destination for writing JSON text.</param> | ||
| <param name="state">A struct that contains the reader state. On the first call to the constructor, it should reflect a default state; otherwise, it should capture the state from the previous instance instance of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> and pass that back.</param> | ||
| <summary>Initializes a new instance of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> class with the specified <paramref name="bufferWriter" />.</summary> |
| ## Remarks | ||
| Unlike the <xref: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 |
There was a problem hiding this comment.
Not reading in this case, but writing. This issue appears in our source comments too:
https://github.com/dotnet/corefx/blob/ce62a086814fdfecea1d6ba6657c3fb88763e1d6/src/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.cs#L84
| <param name="escape">To be added.</param> | ||
| <summary>To be added.</summary> | ||
| <param name="utf8Value">The UTF-8 encoded value to be written as a JSON comment.</param> | ||
| <param name="escape"><see langword="false" /> to indicate the writer should assume the property name is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> |
There was a problem hiding this comment.
This API doesn't contain "property name". Looks like copy/paste error.
writer should assume the property name value is properly escaped
| <param name="escape"><see langword="false" /> to indicate the writer should assume the property name is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> | |
| <param name="escape"><see langword="false" /> to indicate the writer should assume the value is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> |
| <param name="escape">To be added.</param> | ||
| <summary>To be added.</summary> | ||
| <param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment.</param> | ||
| <param name="escape"><see langword="false" /> to indicate the writer should assume the property name is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> |
There was a problem hiding this comment.
Same here/below.
| <param name="escape"><see langword="false" /> to indicate the writer should assume the property name is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> | |
| <param name="escape"><see langword="false" /> to indicate the writer should assume the value is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> |
| <param name="escape">To be added.</param> | ||
| <summary>To be added.</summary> | ||
| <param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON string element of a JSON array.</param> | ||
| <param name="escape"><see langword="false" /> to indicate the writer should assume the property name is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> |
There was a problem hiding this comment.
Here too. Everywhere we have WriteStringValue overloads, the API doesn't contain a property name parameter.
| <param name="escape"><see langword="false" /> to indicate the writer should assume the property name is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> | |
| <param name="escape"><see langword="false" /> to indicate the writer should assume the value is properly escaped and skips the escaping step; otherwise, <see langword="true" />. This is an optional parameter and its default value is <see langword="true" />.</param> |
5 participants
No description provided.