Add documentation for IAsyncDisposable (#2575)

* Add documentation for IAsyncDisposable

Based on source code comments (https://github.com/dotnet/corefx/blob/master/src/Common/src/CoreLib/System/IAsyncDisposable.cs) and Async Streams proposal description (https://github.com/dotnet/csharplang/blob/master/proposals/csharp-8.0/async-streams.md).

* Update IAsyncDisposable.xml

* Apply suggestions from code review

Co-Authored-By: Ron Petrusha <[email protected]>

* Fix xref tag

Author: MSDN-WhiteKnight

xml/System/IAsyncDisposable.xml

@@ -15,8 +15,34 @@
   </AssemblyInfo>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Provides a mechanism for releasing unmanaged resources asynchronously.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+In .NET, classes that own unmanaged resources usually implement the <xref:System.IDisposable> interface to provide a mechanism for releasing unmanaged resources synchronously. However, in some cases they need to provide an asynchronous mechanism for releasing unmanaged resources in addition to (or instead of) the synchronous one. Providing such a mechanism enables the consumer to perform resource-intensive dispose operations without blocking the main thread of a GUI application for a long time.
+
+The <xref:System.IAsyncDisposable.DisposeAsync%2A?displayProperty=nameWithType> method of this interface returns a <xref:System.Threading.Tasks.ValueTask> that represents the asynchronous dispose operation. Classes that own unmanaged resources implement this method, and the consumer of these classes calls this method on an object when it is no longer needed.
+
+The async methods are used in conjunction with the `async` and `await` keywords in C# and Visual Basic. For more insformation, see [The Task asynchronous programming model in C#](/dotnet/csharp/programming-guide/concepts/async/index) or [Asynchronous Programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/).
+
+### Using an object that implements IAsyncDisposable
+
+If your application uses an object that implements `IAsyncDisposable`, you should call the object's <xref:System.IAsyncDisposable.DisposeAsync%2A> implementation when you are finished using it. To make sure resources are released even in case of an exception, call the <xref:System.IAsyncDisposable.DisposeAsync%2A> method inside a `finally` clause of the `try`/`finally` statement. For more information about the `try`/`finally` pattern, see [try-finally](~/docs/csharp/language-reference/keywords/try-finally.md) (C#) or [Try...Catch...Finally Statement](~/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md) (Visual Basic).
+
+### Implementing IAsyncDisposable	
+	
+You might implement `IAsyncDisposable` in the following situations:
+
+- When developing an asynchronous enumerator that owns unmanaged resources. Asynchronous enumerators are used with the C# 8.0 async streams feature. For more information about async streams, see [Tutorial: Generate and consume async streams using C# 8.0 and .NET Core 3.0](/dotnet/csharp/tutorials/generate-consume-asynchronous-stream).
+
+- When your class owns unmanaged resources and releasing them requires a resource-intensive I/O operation, such as flushing the contents of an intermediate buffer into a file or sending a packet over a network to close a connection.
+
+Use the <xref:System.IAsyncDisposable.DisposeAsync%2A> method to perform whatever cleanup is necessary after using the unmanaged resources, such as freeing, releasing, or resetting the unmanaged resources. For more information about unmanaged resources in .NET, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged).
+ 
+ ]]></format>
+</remarks>
   </Docs>
   <Members>
     <Member MemberName="DisposeAsync">
@@ -40,10 +66,25 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.</summary>
+        <returns>A task that represents the asynchronous dispose operation.</returns>
+        <remarks>
+      <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+Use this method to asynchronously close or release unmanaged resources such as files, streams, and handles held by an instance of the class that implements this interface. Using this method instead of <xref:System.IDisposable.Dispose%2A?displayProperty=nameWithType> enables you to perform a resource-intensive dispose operation without blocking the main thread of a GUI application for a long time.
+
+> [!WARNING]
+>  If you are using a class that implements the <xref:System.IAsyncDisposable> interface, you should call its `DisposeAsync` implementation when you are finished using the class. For more information, see the "Using an object that implements IAsyncDisposable" section in the <xref:System.IAsyncDisposable> topic.
+
+When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's `DisposeAsync` implementation must call `DisposeAsync` on B, which must in turn call `DisposeAsync` on C. An object must also call the `DisposeAsync` method of its base class if the base class implements <xref:System.IAsyncDisposable>.
+
+If an object's `DisposeAsync` method is called more than once, the object must ignore all calls after the first one and synchronously return a successfully completed <xref:System.Threading.Tasks.ValueTask>. The object must not throw an exception if its `DisposeAsync` method is called multiple times. Instance methods other than `DisposeAsync` can throw an <xref:System.ObjectDisposedException> when resources are already disposed.
+ 
+ ]]></format>
+</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>