Skip to content

Commit c7a2189

Browse files
carlossanlopcarlossanlop
authored
Port System.Collections new docs (second pass) (#10209)
* System.Collections.Concurrent * System.Collections.Frozen * System.Collections.Generic * System.Collections.ObjectModel
1 parent fcd88a2 commit c7a2189

16 files changed

+419
-160
lines changed

‎xml/System.Collections.Concurrent/ConcurrentDictionary`2+AlternateLookup`1.xml

Lines changed: 69 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,11 @@
3232
</Attribute>
3333
</Attributes>
3434
<Docs>
35-
<typeparam name="TAlternateKey">To be added.</typeparam>
36-
<summary>To be added.</summary>
35+
<typeparam name="TAlternateKey">The alternate type of a key for performing lookups.</typeparam>
36+
<summary>
37+
<para>Provides a type that may be used to perform operations on a <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /></para>
38+
<para>using a <typeparamref name="TAlternateKey" /> as a key instead of a <typeparamref name="TKey" />.</para>
39+
</summary>
3740
<remarks>To be added.</remarks>
3841
</Docs>
3942
<Members>
@@ -56,10 +59,13 @@
5659
<Parameter Name="key" Type="TAlternateKey" />
5760
</Parameters>
5861
<Docs>
59-
<param name="key">To be added.</param>
60-
<summary>To be added.</summary>
61-
<returns>To be added.</returns>
62+
<param name="key">The alternate key to check.</param>
63+
<summary>Determines whether the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> contains the specified alternate key.</summary>
64+
<returns>
65+
<see langword="true" /> if the key is in the dictionary; otherwise, <see langword="false" />.</returns>
6266
<remarks>To be added.</remarks>
67+
<exception cref="T:System.ArgumentNullException">
68+
<paramref name="key" /> is <see langword="null" />.</exception>
6369
</Docs>
6470
</Member>
6571
<Member MemberName="Dictionary">
@@ -78,7 +84,7 @@
7884
<ReturnType>System.Collections.Concurrent.ConcurrentDictionary&lt;TKey,TValue&gt;</ReturnType>
7985
</ReturnValue>
8086
<Docs>
81-
<summary>To be added.</summary>
87+
<summary>Gets the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> against which this instance performs operations.</summary>
8288
<value>To be added.</value>
8389
<remarks>To be added.</remarks>
8490
</Docs>
@@ -102,10 +108,16 @@
102108
<Parameter Name="key" Type="TAlternateKey" />
103109
</Parameters>
104110
<Docs>
105-
<param name="key">To be added.</param>
106-
<summary>To be added.</summary>
107-
<value>To be added.</value>
111+
<param name="key">The alternate key of the value to get or set.</param>
112+
<summary>Gets or sets the value associated with the specified alternate key.</summary>
113+
<value>
114+
<para>The value associated with the specified alternate key. If the specified alternate key is not found, a get operation throws</para>
115+
<para>a <see cref="T:System.Collections.Generic.KeyNotFoundException" />, and a set operation creates a new element with the specified key.</para>
116+
</value>
108117
<remarks>To be added.</remarks>
118+
<exception cref="T:System.ArgumentNullException">
119+
<paramref name="key" /> is <see langword="null" />.</exception>
120+
<exception cref="T:System.Collections.Generic.KeyNotFoundException">The property is retrieved and alternate key does not exist in the collection.</exception>
109121
</Docs>
110122
</Member>
111123
<Member MemberName="TryAdd">
@@ -128,11 +140,14 @@
128140
<Parameter Name="value" Type="TValue" />
129141
</Parameters>
130142
<Docs>
131-
<param name="key">To be added.</param>
132-
<param name="value">To be added.</param>
133-
<summary>To be added.</summary>
134-
<returns>To be added.</returns>
143+
<param name="key">The alternate key of the element to add.</param>
144+
<param name="value">The value of the element to add.</param>
145+
<summary>Attempts to add the specified key and value to the dictionary.</summary>
146+
<returns>
147+
<see langword="true" /> if the key/value pair was added to the dictionary successfully; otherwise, <see langword="false" />.</returns>
135148
<remarks>To be added.</remarks>
149+
<exception cref="T:System.ArgumentNullException">
150+
<paramref name="key" /> is <see langword="null" />.</exception>
136151
</Docs>
137152
</Member>
138153
<Member MemberName="TryGetValue">
@@ -155,11 +170,16 @@
155170
<Parameter Name="value" Type="TValue" RefType="out" />
156171
</Parameters>
157172
<Docs>
158-
<param name="key">To be added.</param>
159-
<param name="value">To be added.</param>
160-
<summary>To be added.</summary>
173+
<param name="key">The alternate key of the value to get.</param>
174+
<param name="value">
175+
<para>When this method returns, contains the value associated with the specified key, if the key is found;</para>
176+
<para>otherwise, the default value for the type of the value parameter.</para>
177+
</param>
178+
<summary>Gets the value associated with the specified alternate key.</summary>
161179
<returns>To be added.</returns>
162180
<remarks>To be added.</remarks>
181+
<exception cref="T:System.ArgumentNullException">
182+
<paramref name="key" /> is <see langword="null" />.</exception>
163183
</Docs>
164184
</Member>
165185
<Member MemberName="TryGetValue">
@@ -183,12 +203,20 @@
183203
<Parameter Name="value" Type="TValue" RefType="out" />
184204
</Parameters>
185205
<Docs>
186-
<param name="key">To be added.</param>
187-
<param name="actualKey">To be added.</param>
188-
<param name="value">To be added.</param>
189-
<summary>To be added.</summary>
206+
<param name="key">The alternate key of the value to get.</param>
207+
<param name="actualKey">
208+
<para>When this method returns, contains the actual key associated with the alternate key, if the key is found;</para>
209+
<para>otherwise, the default value for the type of the key parameter.</para>
210+
</param>
211+
<param name="value">
212+
<para>When this method returns, contains the value associated with the specified key, if the key is found;</para>
213+
<para>otherwise, the default value for the type of the value parameter.</para>
214+
</param>
215+
<summary>Gets the value associated with the specified alternate key.</summary>
190216
<returns>To be added.</returns>
191217
<remarks>To be added.</remarks>
218+
<exception cref="T:System.ArgumentNullException">
219+
<paramref name="key" /> is <see langword="null" />.</exception>
192220
</Docs>
193221
</Member>
194222
<Member MemberName="TryRemove">
@@ -211,11 +239,17 @@
211239
<Parameter Name="value" Type="TValue" RefType="out" />
212240
</Parameters>
213241
<Docs>
214-
<param name="key">To be added.</param>
215-
<param name="value">To be added.</param>
216-
<summary>To be added.</summary>
217-
<returns>To be added.</returns>
242+
<param name="key">The alternate key of the element to remove.</param>
243+
<param name="value">The removed element.</param>
244+
<summary>
245+
<para>Removes the value with the specified alternate key from the <see cref="T:System.Collections.Generic.Dictionary`2" />,</para>
246+
<para>and copies the element to the value parameter.</para>
247+
</summary>
248+
<returns>
249+
<see langword="true" /> if the element is successfully found and removed; otherwise, <see langword="false" />.</returns>
218250
<remarks>To be added.</remarks>
251+
<exception cref="T:System.ArgumentNullException">
252+
<paramref name="key" /> is <see langword="null" />.</exception>
219253
</Docs>
220254
</Member>
221255
<Member MemberName="TryRemove">
@@ -239,12 +273,18 @@
239273
<Parameter Name="value" Type="TValue" RefType="out" />
240274
</Parameters>
241275
<Docs>
242-
<param name="key">To be added.</param>
243-
<param name="actualKey">To be added.</param>
244-
<param name="value">To be added.</param>
245-
<summary>To be added.</summary>
246-
<returns>To be added.</returns>
276+
<param name="key">The alternate key of the element to remove.</param>
277+
<param name="actualKey">The removed key.</param>
278+
<param name="value">The removed element.</param>
279+
<summary>
280+
<para>Removes the value with the specified alternate key from the <see cref="T:System.Collections.Generic.Dictionary`2" />,</para>
281+
<para>and copies the associated key and element to the value parameter.</para>
282+
</summary>
283+
<returns>
284+
<see langword="true" /> if the element is successfully found and removed; otherwise, <see langword="false" />.</returns>
247285
<remarks>To be added.</remarks>
286+
<exception cref="T:System.ArgumentNullException">
287+
<paramref name="key" /> is <see langword="null" />.</exception>
248288
</Docs>
249289
</Member>
250290
</Members>

‎xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -988,10 +988,18 @@
988988
</TypeParameters>
989989
<Parameters />
990990
<Docs>
991-
<typeparam name="TAlternateKey">To be added.</typeparam>
992-
<summary>To be added.</summary>
993-
<returns>To be added.</returns>
994-
<remarks>To be added.</remarks>
991+
<typeparam name="TAlternateKey">The alternate type of a key for performing lookups.</typeparam>
992+
<summary>
993+
<para>Gets an instance of a type that may be used to perform operations on a <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /></para>
994+
<para>using a <typeparamref name="TAlternateKey" /> as a key instead of a <typeparamref name="TKey" />.</para>
995+
</summary>
996+
<returns>The created lookup instance.</returns>
997+
<remarks>
998+
<para>This instance must be using a comparer that implements <see cref="T:System.Collections.Generic.IAlternateEqualityComparer`2" /> with</para>
999+
<para>
1000+
<typeparamref name="TAlternateKey" /> and <typeparamref name="TKey" />. If it doesn't, an exception will be thrown.</para>
1001+
</remarks>
1002+
<exception cref="T:System.InvalidOperationException">This instance's comparer is not compatible with <typeparamref name="TAlternateKey" />.</exception>
9951003
</Docs>
9961004
</Member>
9971005
<Member MemberName="GetEnumerator">

‎xml/System.Collections.Frozen/FrozenDictionary`2+AlternateLookup`1.xml

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,11 @@
3636
</Attribute>
3737
</Attributes>
3838
<Docs>
39-
<typeparam name="TAlternateKey">To be added.</typeparam>
40-
<summary>To be added.</summary>
39+
<typeparam name="TAlternateKey">The alternate type of a key for performing lookups.</typeparam>
40+
<summary>
41+
<para>Provides a type that may be used to perform operations on a <see cref="T:System.Collections.Frozen.FrozenDictionary`2" /></para>
42+
<para>using a <typeparamref name="TAlternateKey" /> as a key instead of a <typeparamref name="TKey" />.</para>
43+
</summary>
4144
<remarks>To be added.</remarks>
4245
</Docs>
4346
<Members>
@@ -60,10 +63,13 @@
6063
<Parameter Name="key" Type="TAlternateKey" />
6164
</Parameters>
6265
<Docs>
63-
<param name="key">To be added.</param>
64-
<summary>To be added.</summary>
65-
<returns>To be added.</returns>
66+
<param name="key">The alternate key to check.</param>
67+
<summary>Determines whether the <see cref="T:System.Collections.Frozen.FrozenDictionary`2" /> contains the specified alternate key.</summary>
68+
<returns>
69+
<see langword="true" /> if the key is in the dictionary; otherwise, <see langword="false" />.</returns>
6670
<remarks>To be added.</remarks>
71+
<exception cref="T:System.ArgumentNullException">
72+
<paramref name="key" /> is <see langword="null" />.</exception>
6773
</Docs>
6874
</Member>
6975
<Member MemberName="Dictionary">
@@ -82,7 +88,7 @@
8288
<ReturnType>System.Collections.Frozen.FrozenDictionary&lt;TKey,TValue&gt;</ReturnType>
8389
</ReturnValue>
8490
<Docs>
85-
<summary>To be added.</summary>
91+
<summary>Gets the <see cref="T:System.Collections.Frozen.FrozenDictionary`2" /> against which this instance performs operations.</summary>
8692
<value>To be added.</value>
8793
<remarks>To be added.</remarks>
8894
</Docs>
@@ -106,10 +112,16 @@
106112
<Parameter Name="key" Type="TAlternateKey" />
107113
</Parameters>
108114
<Docs>
109-
<param name="key">To be added.</param>
110-
<summary>To be added.</summary>
111-
<value>To be added.</value>
115+
<param name="key">The alternate key of the value to get or set.</param>
116+
<summary>Gets or sets the value associated with the specified alternate key.</summary>
117+
<value>
118+
<para>The value associated with the specified alternate key. If the specified alternate key is not found, a get operation throws</para>
119+
<para>a <see cref="T:System.Collections.Generic.KeyNotFoundException" />, and a set operation creates a new element with the specified key.</para>
120+
</value>
112121
<remarks>To be added.</remarks>
122+
<exception cref="T:System.ArgumentNullException">
123+
<paramref name="key" /> is <see langword="null" />.</exception>
124+
<exception cref="T:System.Collections.Generic.KeyNotFoundException">The alternate key does not exist in the collection.</exception>
113125
</Docs>
114126
</Member>
115127
<Member MemberName="TryGetValue">
@@ -139,11 +151,16 @@
139151
</Parameter>
140152
</Parameters>
141153
<Docs>
142-
<param name="key">To be added.</param>
143-
<param name="value">To be added.</param>
144-
<summary>To be added.</summary>
154+
<param name="key">The alternate key of the value to get.</param>
155+
<param name="value">
156+
<para>When this method returns, contains the value associated with the specified key, if the key is found;</para>
157+
<para>otherwise, the default value for the type of the value parameter.</para>
158+
</param>
159+
<summary>Gets the value associated with the specified alternate key.</summary>
145160
<returns>To be added.</returns>
146161
<remarks>To be added.</remarks>
162+
<exception cref="T:System.ArgumentNullException">
163+
<paramref name="key" /> is <see langword="null" />.</exception>
147164
</Docs>
148165
</Member>
149166
</Members>

‎xml/System.Collections.Frozen/FrozenDictionary`2.xml

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -275,10 +275,18 @@
275275
</TypeParameters>
276276
<Parameters />
277277
<Docs>
278-
<typeparam name="TAlternateKey">To be added.</typeparam>
279-
<summary>To be added.</summary>
280-
<returns>To be added.</returns>
281-
<remarks>To be added.</remarks>
278+
<typeparam name="TAlternateKey">The alternate type of a key for performing lookups.</typeparam>
279+
<summary>
280+
<para>Gets an instance of a type that may be used to perform operations on a <see cref="T:System.Collections.Frozen.FrozenDictionary`2" /></para>
281+
<para>using a <typeparamref name="TAlternateKey" /> as a key instead of a <typeparamref name="TKey" />.</para>
282+
</summary>
283+
<returns>The created lookup instance.</returns>
284+
<remarks>
285+
<para>This instance must be using a comparer that implements <see cref="T:System.Collections.Generic.IAlternateEqualityComparer`2" /> with</para>
286+
<para>
287+
<typeparamref name="TAlternateKey" /> and <typeparamref name="TKey" />. If it doesn't, an exception will be thrown.</para>
288+
</remarks>
289+
<exception cref="T:System.InvalidOperationException">This instance's comparer is not compatible with <typeparamref name="TAlternateKey" />.</exception>
282290
</Docs>
283291
</Member>
284292
<Member MemberName="GetEnumerator">

‎xml/System.Collections.Frozen/FrozenSet.xml

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -73,10 +73,10 @@
7373
</Parameter>
7474
</Parameters>
7575
<Docs>
76-
<typeparam name="T">To be added.</typeparam>
77-
<param name="source">To be added.</param>
78-
<summary>To be added.</summary>
79-
<returns>To be added.</returns>
76+
<typeparam name="T">The type of the values in the set.</typeparam>
77+
<param name="source">The values to use to populate the set.</param>
78+
<summary>Creates a <see cref="T:System.Collections.Frozen.FrozenSet`1" /> with the specified values.</summary>
79+
<returns>A frozen set.</returns>
8080
<remarks>To be added.</remarks>
8181
</Docs>
8282
</Member>
@@ -132,11 +132,11 @@
132132
</Parameter>
133133
</Parameters>
134134
<Docs>
135-
<typeparam name="T">To be added.</typeparam>
136-
<param name="equalityComparer">To be added.</param>
137-
<param name="source">To be added.</param>
138-
<summary>To be added.</summary>
139-
<returns>To be added.</returns>
135+
<typeparam name="T">The type of the values in the set.</typeparam>
136+
<param name="equalityComparer">The comparer implementation to use to compare values for equality. If <see langword="null" />, <see cref="P:System.Collections.Generic.EqualityComparer`1.Default" /> is used.</param>
137+
<param name="source">The values to use to populate the set.</param>
138+
<summary>Creates a <see cref="T:System.Collections.Frozen.FrozenSet`1" /> with the specified values.</summary>
139+
<returns>A frozen set.</returns>
140140
<remarks>To be added.</remarks>
141141
</Docs>
142142
</Member>

‎xml/System.Collections.Frozen/FrozenSet`1+AlternateLookup`1.xml

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,11 @@
4242
</Attribute>
4343
</Attributes>
4444
<Docs>
45-
<typeparam name="TAlternate">To be added.</typeparam>
46-
<summary>To be added.</summary>
45+
<typeparam name="TAlternate">The alternate type of a key for performing lookups.</typeparam>
46+
<summary>
47+
<para>Provides a type that may be used to perform operations on a <see cref="T:System.Collections.Frozen.FrozenSet`1" /></para>
48+
<para>using a <typeparamref name="TAlternate" /> as a key instead of a <typeparamref name="T" />.</para>
49+
</summary>
4750
<remarks>To be added.</remarks>
4851
</Docs>
4952
<Members>
@@ -66,9 +69,10 @@
6669
<Parameter Name="item" Type="TAlternate" />
6770
</Parameters>
6871
<Docs>
69-
<param name="item">To be added.</param>
70-
<summary>To be added.</summary>
71-
<returns>To be added.</returns>
72+
<param name="item">The element to locate in the set.</param>
73+
<summary>Determines whether a set contains the specified element.</summary>
74+
<returns>
75+
<see langword="true" /> if the set contains the specified element; otherwise, <see langword="false" />.</returns>
7276
<remarks>To be added.</remarks>
7377
</Docs>
7478
</Member>
@@ -88,7 +92,7 @@
8892
<ReturnType>System.Collections.Frozen.FrozenSet&lt;T&gt;</ReturnType>
8993
</ReturnValue>
9094
<Docs>
91-
<summary>To be added.</summary>
95+
<summary>Gets the <see cref="T:System.Collections.Frozen.FrozenSet`1" /> against which this instance performs operations.</summary>
9296
<value>To be added.</value>
9397
<remarks>To be added.</remarks>
9498
</Docs>
@@ -120,10 +124,10 @@
120124
</Parameter>
121125
</Parameters>
122126
<Docs>
123-
<param name="equalValue">To be added.</param>
124-
<param name="actualValue">To be added.</param>
125-
<summary>To be added.</summary>
126-
<returns>To be added.</returns>
127+
<param name="equalValue">The value to search for.</param>
128+
<param name="actualValue">The value from the set that the search found, or the default value of <typeparamref name="T" /> when the search yielded no match.</param>
129+
<summary>Searches the set for a given value and returns the equal value it finds, if any.</summary>
130+
<returns>A value indicating whether the search was successful.</returns>
127131
<remarks>To be added.</remarks>
128132
</Docs>
129133
</Member>

0 commit comments

Comments
 (0)