Document exceptions in OrderedDictionary (#113091)

* Document exceptions in OrderedDictionary

* tweak SetAt param doc

Author: Rob-Hague

src/libraries/System.Collections/src/System/Collections/Generic/OrderedDictionary.cs

@@ -97,7 +97,7 @@ public OrderedDictionary(IEqualityComparer<TKey>? comparer) : this(0, comparer)
         /// The <see cref="IEqualityComparer{TKey}"/> implementation to use when comparing keys,
         /// or null to use the default <see cref="EqualityComparer{TKey}"/> for the type of the key.
         /// </param>
-        /// <exception cref="ArgumentOutOfRangeException">capacity is less than 0.</exception>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="capacity"/> is less than 0.</exception>
         public OrderedDictionary(int capacity, IEqualityComparer<TKey>? comparer)
         {
             ThrowIfNegative(capacity);
@@ -145,7 +145,7 @@ public OrderedDictionary(int capacity, IEqualityComparer<TKey>? comparer)
         /// The <see cref="IDictionary{TKey, TValue}"/> whose elements are copied to the new <see cref="OrderedDictionary{TKey, TValue}"/>.
         /// The initial order of the elements in the new collection is the order the elements are enumerated from the supplied dictionary.
         /// </param>
-        /// <exception cref="ArgumentNullException"><paramref name="dictionary"/> is null.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="dictionary"/> is <see langword="null"/>.</exception>
         public OrderedDictionary(IDictionary<TKey, TValue> dictionary) : this(dictionary, null)
         {
         }
@@ -162,7 +162,7 @@ public OrderedDictionary(IDictionary<TKey, TValue> dictionary) : this(dictionary
         /// The <see cref="IEqualityComparer{TKey}"/> implementation to use when comparing keys,
         /// or null to use the default <see cref="EqualityComparer{TKey}"/> for the type of the key.
         /// </param>
-        /// <exception cref="ArgumentNullException"><paramref name="dictionary"/> is null.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="dictionary"/> is <see langword="null"/>.</exception>
         public OrderedDictionary(IDictionary<TKey, TValue> dictionary, IEqualityComparer<TKey>? comparer) :
             this(dictionary?.Count ?? 0, comparer)
         {
@@ -179,7 +179,7 @@ public OrderedDictionary(IDictionary<TKey, TValue> dictionary, IEqualityComparer
         /// The <see cref="IEnumerable{T}"/> whose elements are copied to the new <see cref="OrderedDictionary{TKey, TValue}"/>.
         /// The initial order of the elements in the new collection is the order the elements are enumerated from the supplied collection.
         /// </param>
-        /// <exception cref="ArgumentNullException"><paramref name="collection"/> is null.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="collection"/> is <see langword="null"/>.</exception>
         public OrderedDictionary(IEnumerable<KeyValuePair<TKey, TValue>> collection) : this(collection, null)
         {
         }
@@ -196,7 +196,7 @@ public OrderedDictionary(IEnumerable<KeyValuePair<TKey, TValue>> collection) : t
         /// The <see cref="IEqualityComparer{TKey}"/> implementation to use when comparing keys,
         /// or null to use the default <see cref="EqualityComparer{TKey}"/> for the type of the key.
         /// </param>
-        /// <exception cref="ArgumentNullException"><paramref name="collection"/> is null.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="collection"/> is <see langword="null"/>.</exception>
         public OrderedDictionary(IEnumerable<KeyValuePair<TKey, TValue>> collection, IEqualityComparer<TKey>? comparer) :
             this((collection as ICollection<KeyValuePair<TKey, TValue>>)?.Count ?? 0, comparer)
         {
@@ -359,7 +359,7 @@ KeyValuePair<TKey, TValue> IList<KeyValuePair<TKey, TValue>>.this[int index]
         /// <summary>Gets or sets the value associated with the specified key.</summary>
         /// <param name="key">The key of the value to get or set.</param>
         /// <returns>The value associated with the specified key. If the specified key is not found, a get operation throws a <see cref="KeyNotFoundException"/>, and a set operation creates a new element with the specified key.</returns>
-        /// <exception cref="ArgumentNullException"><paramref name="key"/> is null.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         /// <exception cref="KeyNotFoundException">The property is retrieved and <paramref name="key"/> does not exist in the collection.</exception>
         /// <remarks>Setting the value of an existing key does not impact its order in the collection.</remarks>
         public TValue this[TKey key]
@@ -479,8 +479,8 @@ private bool TryInsert(int index, TKey key, TValue value, InsertionBehavior beha
 
         /// <summary>Adds the specified key and value to the dictionary.</summary>
         /// <param name="key">The key of the element to add.</param>
-        /// <param name="value">The value of the element to add. The value can be null for reference types.</param>
-        /// <exception cref="ArgumentNullException">key is null.</exception>
+        /// <param name="value">The value of the element to add. The value can be <see langword="null"/> for reference types.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         /// <exception cref="ArgumentException">An element with the same key already exists in the <see cref="OrderedDictionary{TKey, TValue}"/>.</exception>
         public void Add(TKey key, TValue value)
         {
@@ -491,17 +491,17 @@ public void Add(TKey key, TValue value)
 
         /// <summary>Adds the specified key and value to the dictionary if the key doesn't already exist.</summary>
         /// <param name="key">The key of the element to add.</param>
-        /// <param name="value">The value of the element to add. The value can be null for reference types.</param>
-        /// <exception cref="ArgumentNullException">key is null.</exception>
-        /// <returns>true if the key didn't exist and the key and value were added to the dictionary; otherwise, false.</returns>
+        /// <param name="value">The value of the element to add. The value can be <see langword="null"/> for reference types.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
+        /// <returns><see langword="true"/> if the key didn't exist and the key and value were added to the dictionary; otherwise, <see langword="false"/>.</returns>
         public bool TryAdd(TKey key, TValue value) => TryAdd(key, value, out _);
 
         /// <summary>Adds the specified key and value to the dictionary if the key doesn't already exist.</summary>
         /// <param name="key">The key of the element to add.</param>
-        /// <param name="value">The value of the element to add. The value can be null for reference types.</param>
+        /// <param name="value">The value of the element to add. The value can be <see langword="null"/> for reference types.</param>
         /// <param name="index">The index of the added or existing <paramref name="key"/>. This is always a valid index into the dictionary.</param>
-        /// <exception cref="ArgumentNullException">key is null.</exception>
-        /// <returns>true if the key didn't exist and the key and value were added to the dictionary; otherwise, false.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
+        /// <returns><see langword="true"/> if the key didn't exist and the key and value were added to the dictionary; otherwise, <see langword="false"/>.</returns>
         public bool TryAdd(TKey key, TValue value, out int index)
         {
             ThrowIfNull(key);
@@ -546,12 +546,13 @@ public void Clear()
 
         /// <summary>Determines whether the <see cref="OrderedDictionary{TKey, TValue}"/> contains the specified key.</summary>
         /// <param name="key">The key to locate in the <see cref="OrderedDictionary{TKey, TValue}"/>.</param>
-        /// <returns>true if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified key; otherwise, false.</returns>
+        /// <returns><see langword="true"/> if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified key; otherwise, <see langword="false"/>.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         public bool ContainsKey(TKey key) => IndexOf(key) >= 0;
 
         /// <summary>Determines whether the <see cref="OrderedDictionary{TKey, TValue}"/> contains a specific value.</summary>
         /// <param name="value">The value to locate in the <see cref="OrderedDictionary{TKey, TValue}"/>. The value can be null for reference types.</param>
-        /// <returns>true if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified value; otherwise, false.</returns>
+        /// <returns><see langword="true"/> if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified value; otherwise, <see langword="false"/>.</returns>
         public bool ContainsValue(TValue value)
         {
             int count = _count;
@@ -607,7 +608,7 @@ public KeyValuePair<TKey, TValue> GetAt(int index)
         /// <summary>Determines the index of a specific key in the <see cref="OrderedDictionary{TKey, TValue}"/>.</summary>
         /// <param name="key">The key to locate.</param>
         /// <returns>The index of <paramref name="key"/> if found; otherwise, -1.</returns>
-        /// <exception cref="ArgumentNullException"><paramref name="key"/> is null.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         public int IndexOf(TKey key)
         {
             ThrowIfNull(key);
@@ -717,7 +718,7 @@ private int IndexOf(TKey key, ref uint outHashCode, ref uint outCollisionCount)
         /// <param name="index">The zero-based index at which item should be inserted.</param>
         /// <param name="key">The key to insert.</param>
         /// <param name="value">The value to insert.</param>
-        /// <exception cref="ArgumentNullException">key is null.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         /// <exception cref="ArgumentException">An element with the same key already exists in the <see cref="OrderedDictionary{TKey, TValue}"/>.</exception>
         /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is less than 0 or greater than <see cref="Count"/>.</exception>
         public void Insert(int index, TKey key, TValue value)
@@ -734,13 +735,15 @@ public void Insert(int index, TKey key, TValue value)
 
         /// <summary>Removes the value with the specified key from the <see cref="OrderedDictionary{TKey, TValue}"/>.</summary>
         /// <param name="key">The key of the element to remove.</param>
-        /// <returns></returns>
+        /// <returns><see langword="true"/> if the element is successfully found and removed; otherwise, <see langword="false"/>.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         public bool Remove(TKey key) => Remove(key, out _);
 
         /// <summary>Removes the value with the specified key from the <see cref="OrderedDictionary{TKey, TValue}"/> and copies the element to the value parameter.</summary>
         /// <param name="key">The key of the element to remove.</param>
         /// <param name="value">The removed element.</param>
-        /// <returns>true if the element is successfully found and removed; otherwise, false.</returns>
+        /// <returns><see langword="true"/> if the element is successfully found and removed; otherwise, <see langword="false"/>.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         public bool Remove(TKey key, [MaybeNullWhen(false)] out TValue value)
         {
             ThrowIfNull(key);
@@ -764,6 +767,7 @@ public bool Remove(TKey key, [MaybeNullWhen(false)] out TValue value)
 
         /// <summary>Removes the key/value pair at the specified index.</summary>
         /// <param name="index">The zero-based index of the item to remove.</param>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is less than 0 or greater than or equal to <see cref="Count"/>.</exception>
         public void RemoveAt(int index)
         {
             int count = _count;
@@ -789,8 +793,9 @@ public void RemoveAt(int index)
         }
 
         /// <summary>Sets the value for the key at the specified index.</summary>
-        /// <param name="index">The zero-based index of the element to get or set.</param>
+        /// <param name="index">The zero-based index at which to set the value.</param>
         /// <param name="value">The value to store at the specified index.</param>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is less than 0 or greater than or equal to <see cref="Count"/>.</exception>
         public void SetAt(int index, TValue value)
         {
             if ((uint)index >= (uint)_count)
@@ -804,10 +809,12 @@ public void SetAt(int index, TValue value)
         }
 
         /// <summary>Sets the key/value pair at the specified index.</summary>
-        /// <param name="index">The zero-based index of the element to get or set.</param>
+        /// <param name="index">The zero-based index at which to set the key/value pair.</param>
         /// <param name="key">The key to store at the specified index.</param>
         /// <param name="value">The value to store at the specified index.</param>
-        /// <exception cref="ArgumentException"></exception>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
+        /// <exception cref="ArgumentException">An element with the same key already exists at an index different to <paramref name="index"/>.</exception>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is less than 0 or greater than or equal to <see cref="Count"/>.</exception>
         public void SetAt(int index, TKey key, TValue value)
         {
             if ((uint)index >= (uint)_count)
@@ -910,7 +917,8 @@ public void TrimExcess(int capacity)
         /// When this method returns, contains the value associated with the specified key, if the key is found;
         /// otherwise, the default value for the type of the value parameter.
         /// </param>
-        /// <returns>true if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified key; otherwise, false.</returns>
+        /// <returns><see langword="true"/> if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified key; otherwise, <see langword="false"/>.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         public bool TryGetValue(TKey key, [MaybeNullWhen(false)] out TValue value) => TryGetValue(key, out value, out _);
 
         /// <summary>Gets the value associated with the specified key.</summary>
@@ -920,7 +928,8 @@ public void TrimExcess(int capacity)
         /// otherwise, the default value for the type of the value parameter.
         /// </param>
         /// <param name="index">The index of <paramref name="key"/> if found; otherwise, -1.</param>
-        /// <returns>true if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified key; otherwise, false.</returns>
+        /// <returns><see langword="true"/> if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified key; otherwise, <see langword="false"/>.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
         public bool TryGetValue(TKey key, [MaybeNullWhen(false)] out TValue value, out int index)
         {
             ThrowIfNull(key);