doc(async): some comments on async I/O

Author: richardschneider

README.md

@@ -14,7 +14,7 @@ More information, including the Class Reference, is on the [Project](https://ric
 ## Features
 
 - Targets .NET Framework 4.5, .NET Standard 1.4 and .NET Standard 2.0
-- Asynchronous I/O to an IPFS server
+- [Asynchronous I/O](https://richardschneider.github.io/net-ipfs-api/articles/async.html) to an IPFS server
 - Supports [cancellation](https://richardschneider.github.io/net-ipfs-api/articles/cancellation.html) of all requests to the IPFS Server
 - C# style access to the [ipfs core interface](https://github.com/ipfs/interface-ipfs-core#api)
   - [Block API](https://richardschneider.github.io/net-ipfs-api/api/Ipfs.Api.BlockApi.html)

doc/Documentation.csproj

@@ -89,6 +89,7 @@
     <Content Include="template\fonts\Lato-Regular.woff" />
     <Content Include="template\fonts\Lato-Regular.woff2" />
     <Content Include="articles\cancellation.md" />
+    <Content Include="articles\async.md" />
     <None Include="Web.Debug.config">
       <DependentUpon>Web.config</DependentUpon>
     </None>

doc/articles/async.md

@@ -0,0 +1,24 @@
+# Asynchronous I/O
+
+All requests to the IPFS server are [asynchronous](https://docs.microsoft.com/en-us/dotnet/csharp/async),
+which does not block current thread.
+
+This means that callers should **normally** use the `async/await` paradigm
+
+```cs
+async Task<string> AddText()
+{
+	var result = await ipfs.FileSystem.AddTextAsync("I am pinned");
+	return result.Hash;
+}
+```
+
+If you need to perform a synchronous operation, then this can work
+
+```cs
+string AddText()
+{
+	var result = ipfs.FileSystem.AddTextAsync("I am pinned").Result;
+	return result.Hash;
+}
+```

doc/articles/toc.yml

@@ -2,3 +2,5 @@
   href: intro.md
 - name: Cancellation
   href: cancellation.md
+- name: Asynchronous I/O
+  href: async.md