Skip to content

Adding docs for Unsafe Apis in System.Runtime.CompilerServices #2819

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
Jul 25, 2019
Merged

Adding docs for Unsafe Apis in System.Runtime.CompilerServices #2819

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5fbeba1
adding docs
Anipik Jul 24, 2019
7cdd244
summary on one line and comppare -> compare
Anipik Jul 24, 2019
dbd6aee
adding specified prefix
Anipik Jul 24, 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
47 changes: 22 additions & 25 deletions xml/System.Runtime.CompilerServices/Unsafe.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,11 @@
<Parameter Name="elementOffset" Type="System.Int32" Index="1" FrameworkAlternate="dotnet-plat-ext-2.1;dotnet-plat-ext-2.2;netcore-3.0" />
</Parameters>
<Docs>
<typeparam name="T">To be added.</typeparam>
<param name="source">To be added.</param>
<param name="elementOffset">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The type of void pointer.</typeparam>
<param name="source">The void pointer to add the offset to.</param>
<param name="elementOffset">The offset to add.</param>
<summary>Adds an element offset to the given void pointer.</summary>
<returns>A new void pointer that reflects the addition of offset to the specified pointer.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -185,9 +185,7 @@
<typeparam name="T">The type of reference.</typeparam>
<param name="left">The first reference to compare.</param>
<param name="right">The second reference to compare.</param>
<summary>
Determines whether the specified references point to the same location.
</summary>
<summary>Determines whether the specified references point to the same location.</summary>
<returns>
<see langword="true" /> if <paramref name="left" /> and <paramref name="right" /> point to the same location; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
Expand Down Expand Up @@ -764,11 +762,11 @@
<Parameter Name="right" Type="T" RefType="ref" Index="1" FrameworkAlternate="dotnet-plat-ext-2.1;dotnet-plat-ext-2.2;netcore-3.0" />
</Parameters>
<Docs>
<typeparam name="T">To be added.</typeparam>
<param name="left">To be added.</param>
<param name="right">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The type of the reference.</typeparam>
<param name="left">The first value to compare.</param>
<param name="right">The second value to compare.</param>
<summary>Returns a value that indicates whether a specified reference is greater than another specified reference.</summary>
<returns><see langword="true" /> if <paramref name="left" /> is greater than <paramref name="right" />; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -797,11 +795,11 @@
<Parameter Name="right" Type="T" RefType="ref" Index="1" FrameworkAlternate="dotnet-plat-ext-2.1;dotnet-plat-ext-2.2;netcore-3.0" />
</Parameters>
<Docs>
<typeparam name="T">To be added.</typeparam>
<param name="left">To be added.</param>
<param name="right">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The type of the reference.</typeparam>
<param name="left">The first value to compare.</param>
<param name="right">The second value to compare.</param>
<summary>Returns a value that indicates whether a specified reference is less than another specified reference.</summary>
<returns><see langword="true" /> if <paramref name="left" /> is less than <paramref name="right" />; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -964,11 +962,11 @@
<Parameter Name="elementOffset" Type="System.Int32" Index="1" FrameworkAlternate="dotnet-plat-ext-2.1;dotnet-plat-ext-2.2;netcore-3.0" />
</Parameters>
<Docs>
<typeparam name="T">To be added.</typeparam>
<param name="source">To be added.</param>
<param name="elementOffset">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The type of the void pointer.</typeparam>
<param name="source">The void pointer to subtract the offset from.</param>
<param name="elementOffset">The offset to subtract.</param>
<summary>Subtracts an element offset from the given void pointer.</summary>
<returns>A new void pointer that reflects the subtraction of offset from the specified pointer.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -1062,8 +1060,7 @@
<Docs>
<typeparam name="T">The type of reference.</typeparam>
<param name="source">The reference to subtract the offset from.</param>
<param name="bytesOffset">The offset to subtract.</param>
<param name="byteOffset">To be added.</param>
<param name="byteOffset">The offset to subtract.</param>
Copy link
Contributor

@carlossanlop carlossanlop Jul 24, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

You removed one of the parameters from here. I suspect it was a duplicate. This happens when the parameter name does not match in the source file and the ref file. The official one is the one in the ref file. Which one is the correct one, can you please confirm?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

yes byteOffset is the name of parameter in the ref file

Copy link
Contributor

Choose a reason for hiding this comment

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

That is interesting because the Parameters section, signatures, etc. only shows one of them.

@joelmartinez is this a bug in mdoc?

Copy link
Contributor

Choose a reason for hiding this comment

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

I remembered there's another possible case: if the parameter name is changed from one version to another, they both show up, and both need to be documented, not just one.

@joelmartinez may know the true answer for this.

Copy link
Contributor

Choose a reason for hiding this comment

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

This issue should be resolved in the next mdoc release (5.7.4.10) ... ETA is soon, but not immediately, so manual interventions for this is ideal.

Copy link
Contributor

Choose a reason for hiding this comment

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

I thought of this too but then the parameter would have additional information to convey this like here where you see different frameworkalternate values for each parameter:
https://github.com/dotnet/dotnet-api-docs/blob/master/xml/Microsoft.VisualBasic/Collection.xml#L1161

<summary>
Subtracts a byte offset from the given reference.
</summary>
Expand Down