Skip to content

Add missing docs for System.Collections[.Generic] #4121

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 4 commits into from
Apr 29, 2020
Merged

Add missing docs for System.Collections[.Generic] #4121

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f98df66
Add missing docs for System.Collections[.Generic]
layomia Apr 17, 2020
d67a324
Add exceptions
layomia Apr 20, 2020
e42c4c8
Add System. prefix to exceptions
layomia Apr 22, 2020
3c59e62
Address feedback - use tool to port exceptions
layomia Apr 28, 2020
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
24 changes: 14 additions & 10 deletions xml/System.Collections.Generic/Dictionary`2.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<Type Name="Dictionary&lt;TKey,TValue&gt;" FullName="System.Collections.Generic.Dictionary&lt;TKey,TValue&gt;">
<Type Name="Dictionary&lt;TKey,TValue&gt;" FullName="System.Collections.Generic.Dictionary&lt;TKey,TValue&gt;">
<TypeSignature Language="C#" Value="public class Dictionary&lt;TKey,TValue&gt; : System.Collections.Generic.ICollection&lt;System.Collections.Generic.KeyValuePair&lt;TKey,TValue&gt;&gt;, System.Collections.Generic.IDictionary&lt;TKey,TValue&gt;, System.Collections.Generic.IEnumerable&lt;System.Collections.Generic.KeyValuePair&lt;TKey,TValue&gt;&gt;, System.Collections.Generic.IReadOnlyCollection&lt;System.Collections.Generic.KeyValuePair&lt;TKey,TValue&gt;&gt;, System.Collections.Generic.IReadOnlyDictionary&lt;TKey,TValue&gt;, System.Collections.IDictionary" 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.6" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit Dictionary`2&lt;TKey, TValue&gt; extends System.Object implements class System.Collections.Generic.ICollection`1&lt;valuetype System.Collections.Generic.KeyValuePair`2&lt;!TKey, !TValue&gt;&gt;, class System.Collections.Generic.IDictionary`2&lt;!TKey, !TValue&gt;, class System.Collections.Generic.IEnumerable`1&lt;valuetype System.Collections.Generic.KeyValuePair`2&lt;!TKey, !TValue&gt;&gt;, class System.Collections.Generic.IReadOnlyCollection`1&lt;valuetype System.Collections.Generic.KeyValuePair`2&lt;!TKey, !TValue&gt;&gt;, class System.Collections.Generic.IReadOnlyDictionary`2&lt;!TKey, !TValue&gt;, class System.Collections.ICollection, class System.Collections.IDictionary, class System.Collections.IEnumerable" 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.6" />
<TypeSignature Language="DocId" Value="T:System.Collections.Generic.Dictionary`2" />
Expand Down Expand Up @@ -331,9 +331,10 @@
<Parameter Name="collection" Type="System.Collections.Generic.IEnumerable&lt;System.Collections.Generic.KeyValuePair&lt;TKey,TValue&gt;&gt;" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0" />
</Parameters>
<Docs>
<param name="collection">To be added.</param>
<summary>To be added.</summary>
<param name="collection">The <see cref="T:System.Collections.Generic.IEnumerable`1" /> whose elements are copied to the new <see cref="T:System.Collections.Generic.Dictionary`2" />.</param>
<summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.Dictionary`2" /> class that contains elements copied from the specified <see cref="T:System.Collections.Generic.IEnumerable`1" />.</summary>
<remarks>To be added.</remarks>
<exception cref="System.ArgumentException"><paramref name="collection" /> contains one or more duplicated keys.</exception>
Copy link
Contributor

@carlossanlop carlossanlop Apr 24, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

Hey @layomia did you manually add the exceptions or did you port them with the tool? I ask because the exception cref DocIDs are incomplete (missing the API category prefix), and if it's the tool's fault, I should get it fixed.

This is how it should look:

Suggested change
<exception cref="System.ArgumentException"><paramref name="collection" /> contains one or more duplicated keys.</exception>
<exception cref="T:System.ArgumentException">
<paramref name="collection" /> contains one or more duplicated keys.</exception>

Also, if the inner value of the <exception> starts with an xml tag, we usually prefer to start the text with an endline.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I added them manually in e42c4c8, but used the tool to port the in the new commit. It missed the one added in Queue1.xml (not sure how), so I applied your suggestion in e0f79cf and rebased.

The command I used was:

DocsPortingTool -docs D:\repos\dotnet-api-docs\xml -tripleslash D:\repos\dotnet_runtime\artifacts\bin\coreclr\Windows_NT.x64.Release\IL\,D:\repos\dotnet_runtime\artifacts\bin\ -includedassemblies System.Collections,System.Collections.Generic,mscorlib -excludedassemblies System.Collections.Immutable,System.Collections.Specialized,System.Collections.Concurrent -save true -skipExceptions false

</Docs>
</Member>
<Member MemberName=".ctor">
Expand Down Expand Up @@ -567,10 +568,11 @@
<Parameter Name="comparer" Type="System.Collections.Generic.IEqualityComparer&lt;TKey&gt;" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0" />
</Parameters>
<Docs>
<param name="collection">To be added.</param>
<param name="comparer">To be added.</param>
<summary>To be added.</summary>
<param name="collection">The <see cref="T:System.Collections.Generic.IEnumerable`1" /> whose elements are copied to the new <see cref="T:System.Collections.Generic.Dictionary`2" />.</param>
<param name="comparer">The <see cref="T:System.Collections.Generic.IEqualityComparer`1" /> implementation to use when comparing keys, or <see langword="null" /> to use the default <see cref="T:System.Collections.Generic.EqualityComparer`1" /> for the type of the key.</param>
<summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.Dictionary`2" /> class that contains elements copied from the specified <see cref="T:System.Collections.Generic.IEnumerable`1" /> and uses the specified <see cref="T:System.Collections.Generic.IEqualityComparer`1" />.</summary>
<remarks>To be added.</remarks>
<exception cref="System.ArgumentException"><paramref name="collection" /> contains one or more duplicated keys.</exception>
</Docs>
</Member>
<Member MemberName=".ctor">
Expand Down Expand Up @@ -1506,11 +1508,13 @@
<Parameter Name="value" Type="TValue" RefType="out" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0" />
</Parameters>
<Docs>
<param name="key">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="key">The key of the element to remove.</param>
<param name="value">The removed element.</param>
<summary>Removes the value with the specified key from the <see cref="T:System.Collections.Generic.Dictionary`2" />, and copies the element to the <paramref name="value" /> parameter.</summary>
<returns>
<see langword="true" /> if the element is successfully found and removed; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
<exception cref="System.ArgumentNullException"><paramref name="key" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="System.Collections.Generic.ICollection&lt;System.Collections.Generic.KeyValuePair&lt;TKey,TValue&gt;&gt;.Add">
Expand Down
8 changes: 4 additions & 4 deletions xml/System.Collections.Generic/KeyValuePair`2.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<Type Name="KeyValuePair&lt;TKey,TValue&gt;" FullName="System.Collections.Generic.KeyValuePair&lt;TKey,TValue&gt;">
<Type Name="KeyValuePair&lt;TKey,TValue&gt;" FullName="System.Collections.Generic.KeyValuePair&lt;TKey,TValue&gt;">
<TypeSignature Language="C#" Value="public struct KeyValuePair&lt;TKey,TValue&gt;" />
<TypeSignature Language="ILAsm" Value=".class public sequential ansi sealed beforefieldinit KeyValuePair`2&lt;TKey, TValue&gt; extends System.ValueType" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="DocId" Value="T:System.Collections.Generic.KeyValuePair`2" />
Expand Down Expand Up @@ -159,9 +159,9 @@
<Parameter Name="value" Type="TValue" RefType="out" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0" />
</Parameters>
<Docs>
<param name="key">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<param name="key">The key of the current <see cref="T:System.Collections.Generic.KeyValuePair`2" />.</param>
<param name="value">The value of the current <see cref="T:System.Collections.Generic.KeyValuePair`2" />.</param>
<summary>Deconstructs the current <see cref="T:System.Collections.Generic.KeyValuePair`2" />.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
17 changes: 10 additions & 7 deletions xml/System.Collections.Generic/Queue`1.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<Type Name="Queue&lt;T&gt;" FullName="System.Collections.Generic.Queue&lt;T&gt;">
<Type Name="Queue&lt;T&gt;" FullName="System.Collections.Generic.Queue&lt;T&gt;">
<TypeSignature Language="C#" Value="public class Queue&lt;T&gt; : System.Collections.Generic.IEnumerable&lt;T&gt;, System.Collections.Generic.IReadOnlyCollection&lt;T&gt;, System.Collections.ICollection" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit Queue`1&lt;T&gt; extends System.Object implements class System.Collections.Generic.IEnumerable`1&lt;!T&gt;, class System.Collections.Generic.IReadOnlyCollection`1&lt;!T&gt;, class System.Collections.ICollection, class System.Collections.IEnumerable" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="DocId" Value="T:System.Collections.Generic.Queue`1" />
Expand Down Expand Up @@ -1333,10 +1333,12 @@ finally {
<Parameter Name="result" Type="T" RefType="out" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0" />
</Parameters>
<Docs>
<param name="result">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="result">The removed object.</param>
<summary>Removes the object at the beginning of the <see cref="T:System.Collections.Generic.Queue`1" />, and copies it to the <paramref name="result" /> parameter.</summary>
<returns>
<see langword="true" /> if the object is successfully removed; <see langword="false" /> if the <see cref="T:System.Collections.Generic.Queue`1" /> is empty.</returns>
<remarks>To be added.</remarks>
<exception cref="System.ArgumentNullException"><paramref name="key" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="TryPeek">
Expand Down Expand Up @@ -1368,9 +1370,10 @@ finally {
<Parameter Name="result" Type="T" RefType="out" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0" />
</Parameters>
<Docs>
<param name="result">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="result">If present, the object at the beginning of the <see cref="T:System.Collections.Generic.Queue`1" />; otherwise, the default value of <typeparamref name="T" />.</param>
<summary>Returns a value that indicates whether there is an object at the beginning of the <see cref="T:System.Collections.Generic.Queue`1" />, and if one is present, copies it to the <paramref name="result" /> parameter. The object is not removed from the <see cref="T:System.Collections.Generic.Queue`1" />.</summary>
<returns>
<see langword="true" /> if there is an object at the beginning of the <see cref="T:System.Collections.Generic.Queue`1" />; <see langword="false" /> if the <see cref="T:System.Collections.Generic.Queue`1" /> is empty.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
53 changes: 40 additions & 13 deletions xml/System.Collections.Generic/ReferenceEqualityComparer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<Type Name="ReferenceEqualityComparer" FullName="System.Collections.Generic.ReferenceEqualityComparer">
<Type Name="ReferenceEqualityComparer" FullName="System.Collections.Generic.ReferenceEqualityComparer">
<TypeSignature Language="C#" Value="public sealed class ReferenceEqualityComparer : System.Collections.Generic.IEqualityComparer&lt;object&gt;, System.Collections.IEqualityComparer" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit ReferenceEqualityComparer extends System.Object implements class System.Collections.Generic.IEqualityComparer`1&lt;object&gt;, class System.Collections.IEqualityComparer" />
<TypeSignature Language="DocId" Value="T:System.Collections.Generic.ReferenceEqualityComparer" />
Expand All @@ -21,8 +21,16 @@
</Interface>
</Interfaces>
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<summary>An <see cref="T:System.Collections.Generic.IEqualityComparer`1" /> that uses reference equality (<see cref="M:System.Object.ReferenceEquals(System.Object,System.Object)" />) instead of value equality (<see cref="M:System.Object.Equals(System.Object)" />) when comparing two object instances.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The <xref:System.Collections.Generic.ReferenceEqualityComparer> type cannot be instantiated. Instead, use the <xref:System.Collections.Generic.ReferenceEqualityComparer.Instance> property to access the singleton instance of this type.

]]></format>
</remarks>
</Docs>
<Members>
<Member MemberName="Equals">
Expand All @@ -49,11 +57,21 @@
<Parameter Name="y" Type="System.Object" />
</Parameters>
<Docs>
<param name="x">To be added.</param>
<param name="y">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="x">The first object to compare.</param>
<param name="y">The second object to compare.</param>
<summary>Determines whether two object references refer to the same object instance.</summary>
<returns>
<see langword="true" /> if both <paramref name="x" /> and <paramref name="y" /> refer to the same object instance or if both are <see langword="null" />; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This API is a wrapper around <xref:System.Object.ReferenceEquals(System.Object,System.Object)>.
It is not necessarily equivalent to calling <xref:System.Object.Equals(System.Object,System.Object)>.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="GetHashCode">
Expand All @@ -79,10 +97,19 @@
<Parameter Name="obj" Type="System.Object" />
</Parameters>
<Docs>
<param name="obj">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="obj">The object for which to retrieve the hash code.</param>
<summary>Returns a hash code for the specified object. The returned hash code is based on the object identity, not on the contents of the object.</summary>
<returns>A hash code for the identity of <paramref name="obj" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This API is a wrapper around <xref:System.Runtime.CompilerServices.RuntimeHelpers.GetHashCode(System.Object)>.
It is not necessarily equivalent to calling <xref:System.Object.GetHashCode>.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Instance">
Expand All @@ -101,7 +128,7 @@
<ReturnType>System.Collections.Generic.ReferenceEqualityComparer</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the singleton <see cref="T:System.Collections.Generic.ReferenceEqualityComparer" /> instance.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down
16 changes: 9 additions & 7 deletions xml/System.Collections.Generic/Stack`1.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<Type Name="Stack&lt;T&gt;" FullName="System.Collections.Generic.Stack&lt;T&gt;">
<Type Name="Stack&lt;T&gt;" FullName="System.Collections.Generic.Stack&lt;T&gt;">
<TypeSignature Language="C#" Value="public class Stack&lt;T&gt; : System.Collections.Generic.IEnumerable&lt;T&gt;, System.Collections.Generic.IReadOnlyCollection&lt;T&gt;, System.Collections.ICollection" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit Stack`1&lt;T&gt; extends System.Object implements class System.Collections.Generic.IEnumerable`1&lt;!T&gt;, class System.Collections.Generic.IReadOnlyCollection`1&lt;!T&gt;, class System.Collections.ICollection, class System.Collections.IEnumerable" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="DocId" Value="T:System.Collections.Generic.Stack`1" />
Expand Down Expand Up @@ -1367,9 +1367,10 @@ finally {
<Parameter Name="result" Type="T" RefType="out" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0" />
</Parameters>
<Docs>
<param name="result">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="result">If present, the object at the top of the <see cref="T:System.Collections.Generic.Stack`1" />; otherwise, the default value of <typeparamref name="T" />.</param>
<summary>Returns a value that indicates whether there is an object at the top of the <see cref="T:System.Collections.Generic.Stack`1" />, and if one is present, copies it to the <paramref name="result" /> parameter. The object is not removed from the <see cref="T:System.Collections.Generic.Stack`1" />.</summary>
<returns>
<see langword="true" /> if there is an object at the top of the <see cref="T:System.Collections.Generic.Stack`1" />; <see langword="false" /> if the <see cref="T:System.Collections.Generic.Stack`1" /> is empty.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -1402,9 +1403,10 @@ finally {
<Parameter Name="result" Type="T" RefType="out" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0" />
</Parameters>
<Docs>
<param name="result">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="result">If present, the object at the top of the <see cref="T:System.Collections.Generic.Stack`1" />; otherwise, the default value of <typeparamref name="T" />.</param>
<summary>Returns a value that indicates whether there is an object at the top of the <see cref="T:System.Collections.Generic.Stack`1" />, and if one is present, copies it to the <paramref name="result" /> parameter, and removes it from the <see cref="T:System.Collections.Generic.Stack`1" />.</summary>
<returns>
<see langword="true" /> if there is an object at the top of the <see cref="T:System.Collections.Generic.Stack`1" />; <see langword="false" /> if the <see cref="T:System.Collections.Generic.Stack`1" /> is empty.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
Loading