Skip to content
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.

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

Automatically port System.Text.Json triple slash comments #2737

Merged
merged 34 commits into from
Jul 29, 2019

Conversation

carlossanlop
Copy link
Member

I synced my dotnet-api-docs clone to the latest bits to ensure I had the latest xml API structure from the most recent reference assembly update. I also synced my corefx repo to the latest bits and built them to ensure I had the latest comments.

Area owners @ahsonkhan @steveharter please help double check that the descriptions are all accurate.
@mairaw @rpetrusha for language review.

@carlossanlop carlossanlop self-assigned this Jul 9, 2019
@carlossanlop carlossanlop added 🏁 Release: .NET Core 3.0 :checkered_flag: Release: .NET Core 3.0 new-content Indicates PRs that contain new articles waiting-on-reviews Indicates PRs that cannot be merged because of the lack of reviews labels Jul 9, 2019
@carlossanlop
Copy link
Member Author

@rpetrusha do you mind checking this PR next?

@carlossanlop
Copy link
Member Author

@ahsonkhan @steveharter please help review these ported comments.

@rpetrusha
Copy link

I'm checking it now, @carlossanlop.

@rpetrusha rpetrusha added this to the July 2019 milestone Jul 17, 2019
@rpetrusha rpetrusha removed the waiting-on-reviews Indicates PRs that cannot be merged because of the lack of reviews label Jul 17, 2019
Copy link

@rpetrusha rpetrusha left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've started making changes up to Utf8JsonReader, @carlossanlop. I'll finish tomorrow. Please review what I've finished so far. Tomorrow, I'll finish and approve, you can review, and I'll merge.

xml/System.Text.Json/JsonEncodedText.xml Outdated Show resolved Hide resolved
carlossanlop and others added 2 commits July 25, 2019 11:05
Co-Authored-By: Ahson Khan <ahkha@microsoft.com>
@carlossanlop
Copy link
Member Author

@ahsonkhan there are multiple complex requests that should be addressed separately due to recent changes in source. Let's get this PR merged first, then update the documentation in a new PR.

@rpetrusha @mairaw I addressed the last comments. Can you please take a last look to see if we can get it merged?

Copy link

@rpetrusha rpetrusha left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good, @carlossanlop, except that the build report showed 7 broken crefs. I think I've fixed them all, so I'll merge when a successful build completes.

@rpetrusha rpetrusha added verify-build-before-merge and removed changes-addressed Indicates PRs that had all comments addressed and are awaiting for new review labels Jul 26, 2019
@carlossanlop
Copy link
Member Author

@thanks @rpetrusha. I fixed additional JSON literals that needed to be changed from "word" to <b>word</b>

@rpetrusha rpetrusha merged commit a758205 into dotnet:master Jul 29, 2019
@ahsonkhan
Copy link
Member

ahsonkhan commented Jul 29, 2019

@rpetrusha
Copy link

I think so, @ahsonkhan. We've updated the API reference to reflect Preview 7 APIs, and the build report isn't showing any additional broken links.

@@ -777,9 +789,8 @@ This method does not parse the contents of a JSON string value.
<summary>Gets the value at a specified index when the current value is an <see cref="F:System.Text.Json.JsonValueKind.Array" />.</summary>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like we are missing the docs from source for the the other property, ValueKind:

<Member MemberName="ValueKind">
<MemberSignature Language="C#" Value="public System.Text.Json.JsonValueKind ValueKind { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance valuetype System.Text.Json.JsonValueKind ValueKind" />
<MemberSignature Language="DocId" Value="P:System.Text.Json.JsonElement.ValueKind" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property ValueKind As JsonValueKind" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property System::Text::Json::JsonValueKind ValueKind { System::Text::Json::JsonValueKind get(); };" />
<MemberSignature Language="F#" Value="member this.ValueKind : System.Text.Json.JsonValueKind" Usage="System.Text.Json.JsonElement.ValueKind" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Text.Json</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Text.Json.JsonValueKind</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>

https://github.com/dotnet/corefx/blob/9e994a5923d426f0e64ed3b8f9b93df6f214a42a/src/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs#L32-L38

<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueKind.Array" />.</exception>
<exception cref="T:System.IndexOutOfRangeException">
<paramref name="index" /> is not in the range [0, <see cref="M:System.Text.Json.JsonElement.GetArrayLength" />()).</exception>
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.ValueKind" /> is not <see cref="F:System.Text.Json.JsonValueKind.Array" />.</exception>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are missing parameter description of this indexer:
https://docs.microsoft.com/en-us/dotnet/api/system.text.json.jsonelement.item?view=netcore-3.0#System_Text_Json_JsonElement_Item_System_Int32_

<Docs>
<param name="index">To be added.</param>
<summary>Gets the value at a specified index when the current value is an <see cref="F:System.Text.Json.JsonValueKind.Array" />.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.ValueKind" /> is not <see cref="F:System.Text.Json.JsonValueKind.Array" />.</exception>
<exception cref="T:System.IndexOutOfRangeException"><paramref name="index" /> is not in the range [0, <see cref="M:System.Text.Json.JsonElement.GetArrayLength" />()).</exception>
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
</Docs>

It doesn't exist in source either.

@bartonjs, can you please wordsmith something here to describe the JsonValueKind.Array indexer?
https://github.com/dotnet/corefx/blob/9e994a5923d426f0e64ed3b8f9b93df6f214a42a/src/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs#L40-L61

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
🏁 Release: .NET Core 3.0 :checkered_flag: Release: .NET Core 3.0 new-content Indicates PRs that contain new articles
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants