Skip to content

Document EIIs of integer types (IComparable/IConvertible) #3499

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 1 commit into from
Nov 19, 2019
Merged

Document EIIs of integer types (IComparable/IConvertible) #3499

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
59 changes: 50 additions & 9 deletions xml/System/Int16.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -248,8 +248,7 @@

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="value" /> is not an <see cref="T:System.Int16" />.</exception>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not an <see cref="T:System.Int16" />.</exception>
<altmember cref="T:System.UInt16" />
</Docs>
</Member>
Expand Down Expand Up @@ -1065,10 +1064,44 @@
<Parameter Name="value" Type="System.Object" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6" />
</Parameters>
<Docs>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="value">An object to compare, or <see langword="null" />.</param>
<summary>Compares this instance to a specified object and returns an integer that indicates whether the value of this instance is less than, equal to, or greater than the value of the object.</summary>
<returns>A signed number indicating the relative values of this instance and <paramref name="value" />.
<list type="table">
<listheader>
<term>Return Value</term>
<description>Description</description>
</listheader>
<item>
<term>Less than zero</term>
<description>This instance is less than <paramref name="value" />.</description>
</item>
<item>
<term>Zero</term>
<description>This instance is equal to <paramref name="value" />.</description>
Copy link
Member

Choose a reason for hiding this comment

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

On the interface, we've described this as follows:

This current instance occurs in the same position in the sort order as value.

For all the integral types, those two descriptions mean the same. I'll approve this, and you can decide if you want to use the same consistent language. (This comment applies to all pages in this PR)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hey @BillWagner would you mind elaborating a bit more? I'm not sure where you got that description from, so I'm not understanding your suggestion here.

In case it helps: I got all this text from <Member MemberName="CompareTo"> in this same file (line 181), and simply added the extra remark about the EII.

Copy link
Member

Choose a reason for hiding this comment

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

@carlossanlop The language I quoted above is from the IComparable<T> interface page, in the remarks section.

For all the types in this PR, CompareTo returns 0 if and only if the two instances are equal. That's not true for all types. (Imagine ordering events by date. Two events on the same date would be in the same location in the sort order, but may not be equal.)

For these types, that distinction doesn't matter. I just want to make sure we're consistent and explicit on how we make this decision.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Oh I see what you mean. I think the descriptions are fine for these int types, they were adapter for their specific behavior.

</item>
<item>
<term>Greater than zero</term>
<description>This instance is greater than <paramref name="value" />.

-or-

<paramref name="value" /> is <see langword="null" />.</description>
</item>
</list>
</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.Int16> instance is cast to an <xref:System.IConvertible> interface.

An <xref:System.Int16>, regardless of its value, is considered greater than a null reference.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not an <see cref="T:System.Int16" />.</exception>
</Docs>
</Member>
<Member MemberName="System.IConvertible.GetTypeCode">
Expand Down Expand Up @@ -1097,9 +1130,17 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Returns the <see cref="T:System.TypeCode" /> for value type <see cref="T:System.Int16" />.</summary>
<returns>The enumerated constant, <see cref="F:System.TypeCode.Int16" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.Int16> instance is cast to an <xref:System.IConvertible> interface.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="System.IConvertible.ToBoolean">
Expand Down
59 changes: 50 additions & 9 deletions xml/System/Int32.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -297,8 +297,7 @@

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="value" /> is not an <see cref="T:System.Int32" />.</exception>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not an <see cref="T:System.Int32" />.</exception>
<altmember cref="T:System.UInt32" />
<altmember cref="M:System.Int32.Equals(System.Object)" />
</Docs>
Expand Down Expand Up @@ -1141,10 +1140,44 @@
<Parameter Name="value" Type="System.Object" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6" />
</Parameters>
<Docs>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="value">An object to compare, or <see langword="null" />.</param>
<summary>Compares this instance to a specified object and returns an indication of their relative values.</summary>
<returns>A signed number indicating the relative values of this instance and <paramref name="value" />.
<list type="table">
<listheader>
<term>Return Value</term>
<description>Description</description>
</listheader>
<item>
<term>Less than zero</term>
<description>This instance is less than <paramref name="value" />.</description>
</item>
<item>
<term>Zero</term>
<description>This instance is equal to <paramref name="value" />.</description>
</item>
<item>
<term>Greater than zero</term>
<description>This instance is greater than <paramref name="value" />.

-or-

<paramref name="value" /> is <see langword="null" />.</description>
</item>
</list>
</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.Int32> instance is cast to an <xref:System.IConvertible> interface.

Any instance of <xref:System.Int32>, regardless of its value, is considered greater than `null`.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not an <see cref="T:System.Int32" />.</exception>
</Docs>
</Member>
<Member MemberName="System.IConvertible.GetTypeCode">
Expand Down Expand Up @@ -1173,9 +1206,17 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Returns the <see cref="T:System.TypeCode" /> for value type <see cref="T:System.Int32" />.</summary>
<returns>The enumerated constant, <see cref="F:System.TypeCode.Int32" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.Int32> instance is cast to an <xref:System.IConvertible> interface.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="System.IConvertible.ToBoolean">
Expand Down
58 changes: 50 additions & 8 deletions xml/System/Int64.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,8 +293,7 @@

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="value" /> is not an <see cref="T:System.Int64" />.</exception>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not an <see cref="T:System.Int64" />.</exception>
<altmember cref="T:System.UInt64" />
<altmember cref="M:System.Int64.Equals(System.Object)" />
</Docs>
Expand Down Expand Up @@ -1089,9 +1088,44 @@
<Parameter Name="value" Type="System.Object" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6" />
</Parameters>
<Docs>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="value">An object to compare, or <see langword="null" />.</param>
<summary>Compares this instance to a specified object and returns an indication of their relative values.</summary>
<returns>A signed number indicating the relative values of this instance and <paramref name="value" />.
<list type="table">
<listheader>
<term>Return Value</term>
<description>Description</description>
</listheader>
<item>
<term>Less than zero</term>
<description>This instance is less than <paramref name="value" />.</description>
</item>
<item>
<term>Zero</term>
<description>This instance is equal to <paramref name="value" />.</description>
</item>
<item>
<term>Greater than zero</term>
<description>This instance is greater than <paramref name="value" />.

-or-

<paramref name="value" /> is <see langword="null" />.</description>
</item>
</list>
</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.Int64> instance is cast to an <xref:System.IConvertible> interface.

An <xref:System.Int64>, regardless of its value, is considered greater than a null reference.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not an <see cref="T:System.Int64" />.</exception>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -1121,9 +1155,17 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Returns the <see cref="T:System.TypeCode" /> for value type <see cref="T:System.Int64" />.</summary>
<returns>The enumerated constant, <see cref="F:System.TypeCode.Int64" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.Int64> instance is cast to an <xref:System.IConvertible> interface.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="System.IConvertible.ToBoolean">
Expand Down
59 changes: 50 additions & 9 deletions xml/System/UInt16.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,8 +172,7 @@

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="value" /> is not a <see cref="T:System.UInt16" />.</exception>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not a <see cref="T:System.UInt16" />.</exception>
<altmember cref="M:System.UInt16.Equals(System.Object)" />
</Docs>
</Member>
Expand Down Expand Up @@ -1122,10 +1121,44 @@
<Parameter Name="value" Type="System.Object" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6" />
</Parameters>
<Docs>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="value">An object to compare, or <see langword="null" />.</param>
<summary>Compares this instance to a specified object and returns an indication of their relative values.</summary>
<returns>A signed number indicating the relative values of this instance and <paramref name="value" />.
<list type="table">
<listheader>
<term>Return Value</term>
<description>Description</description>
</listheader>
<item>
<term>Less than zero</term>
<description>This instance is less than <paramref name="value" />.</description>
</item>
<item>
<term>Zero</term>
<description>This instance is equal to <paramref name="value" />.</description>
</item>
<item>
<term>Greater than zero</term>
<description>This instance is greater than <paramref name="value" />.

-or-

<paramref name="value" /> is <see langword="null" />.</description>
</item>
</list>
</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.UInt16> instance is cast to an <xref:System.IConvertible> interface.

Any instance of <xref:System.UInt16>, regardless of its value, is considered greater than `null`.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not a <see cref="T:System.UInt16" />.</exception>
</Docs>
</Member>
<Member MemberName="System.IConvertible.GetTypeCode">
Expand Down Expand Up @@ -1154,9 +1187,17 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Returns the <see cref="T:System.TypeCode" /> for value type <see cref="T:System.UInt16" />.</summary>
<returns>The enumerated constant, <see cref="F:System.TypeCode.UInt16" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.UInt16> instance is cast to an <xref:System.IConvertible> interface.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="System.IConvertible.ToBoolean">
Expand Down
59 changes: 50 additions & 9 deletions xml/System/UInt32.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,8 +172,7 @@

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="value" /> is not a <see cref="T:System.UInt32" />.</exception>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not a <see cref="T:System.UInt32" />.</exception>
<altmember cref="M:System.UInt32.Equals(System.Object)" />
</Docs>
</Member>
Expand Down Expand Up @@ -1135,10 +1134,44 @@
<Parameter Name="value" Type="System.Object" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6" />
</Parameters>
<Docs>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="value">An object to compare, or <see langword="null" />.</param>
<summary>Compares this instance to a specified object and returns an indication of their relative values.</summary>
<returns>A signed number indicating the relative values of this instance and <paramref name="value" />.
<list type="table">
<listheader>
<term>Return Value</term>
<description>Description</description>
</listheader>
<item>
<term>Less than zero</term>
<description>This instance is less than <paramref name="value" />.</description>
</item>
<item>
<term>Zero</term>
<description>This instance is equal to <paramref name="value" />.</description>
</item>
<item>
<term>Greater than zero</term>
<description>This instance is greater than <paramref name="value" />.

-or-

<paramref name="value" /> is <see langword="null" />.</description>
</item>
</list>
</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.UInt32> instance is cast to an <xref:System.IConvertible> interface.

Any instance of <xref:System.UInt32>, regardless of its value, is considered greater than `null`.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException"><paramref name="value" /> is not a <see cref="T:System.UInt32" />.</exception>
</Docs>
</Member>
<Member MemberName="System.IConvertible.GetTypeCode">
Expand Down Expand Up @@ -1167,9 +1200,17 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Returns the <see cref="T:System.TypeCode" /> for value type <see cref="T:System.UInt32" />.</summary>
<returns>The enumerated constant, <see cref="F:System.TypeCode.UInt32" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.UInt32> instance is cast to an <xref:System.IConvertible> interface.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="System.IConvertible.ToBoolean">
Expand Down
Loading