Add missing documentation for TryAdd API (dotnet#2260)

SeanKilleen · mairaw · commit 5930fb62adab · 2019-04-11T23:04:02.000-07:00
* Add missing documentation for TryAdd API

* fix typo

* use lang keywords for true/false

* use ref for Add method

* refer to method directly since we're in the doc for it

* capitalization

* more formal language

* change to cref format based on build feedback

* Update xml/System.Collections.Generic/Dictionary`2.xml

Co-Authored-By: SeanKilleen &lt;SeanKilleen@gmail.com&gt;

* Update xml/System.Collections.Generic/Dictionary`2.xml

Co-Authored-By: SeanKilleen &lt;SeanKilleen@gmail.com&gt;

* Update xml/System.Collections.Generic/Dictionary`2.xml

Co-Authored-By: SeanKilleen &lt;SeanKilleen@gmail.com&gt;

* Apply suggestions from code review

Co-Authored-By: SeanKilleen &lt;SeanKilleen@gmail.com&gt;

* Update xml/System.Collections.Generic/Dictionary`2.xml

Co-Authored-By: SeanKilleen &lt;SeanKilleen@gmail.com&gt;

* fixing link
diff --git a/xml/System.Collections.Generic/Dictionary`2.xml b/xml/System.Collections.Generic/Dictionary`2.xml
@@ -2778,11 +2778,21 @@ finally {
         <Parameter Name="value" Type="TValue" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
       </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>
-        <remarks>To be added.</remarks>
+        <param name="key">The key of the element to add.</param>
+        <param name="value">The value of the element to add. It can be <see langword="null" />.</param>
+        <summary>Attempts to add the specified key and value to the dictionary.</summary>
+        <returns><see langword="true" /> if the key/value pair was added to the dictionary successfully; otherwise, <see langword="false" />.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+
+Unlike the <xref:System.Collections.Generic.Dictionary%602.Add%2A> method, this method doesn't throw an exception if the element with the given key exists in the dictionary. Unlike the Dictionary indexer, `TryAdd` doesn't override the element if the element with the given key exists in the dictionary. If the key already exists, `TryAdd` does nothing and returns `false`.
+
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="key" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="TryGetValue">
@@ -2925,4 +2935,4 @@ finally {
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>
