docs: improve articles

doc/Documentation.csproj

@@ -88,9 +88,10 @@
     <Content Include="template\fonts\Lato-Regular.ttf" />
     <Content Include="template\fonts\Lato-Regular.woff" />
     <Content Include="template\fonts\Lato-Regular.woff2" />
-    <Content Include="articles\cancellation.md" />
     <Content Include="articles\async.md" />
     <Content Include="articles\envvars.md" />
+    <Content Include="articles\client.md" />
+    <Content Include="articles\daemon.md" />
     <None Include="Web.Debug.config">
       <DependentUpon>Web.config</DependentUpon>
     </None>

doc/articles/async.md

@@ -1,24 +1,45 @@
-# 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 a synchronous operation is required, then this can work
-
-```cs
-string AddText()
-{
-	var result = ipfs.FileSystem.AddTextAsync("I am pinned").Result;
-	return result.Hash;
-}
-```
+# 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
+var result = await ipfs.FileSystem.AddTextAsync("I am pinned");
+```
+
+## Synchronous
+
+If a synchronous operation is required, then this can work
+
+```cs
+var result = ipfs.FileSystem.AddTextAsync("I am pinned").Result;
+```
+
+## Cancelling a request
+
+All requests to the IPFS server can be cancelled by supplying 
+an optional [CancellationToken](xref:System.Threading.CancellationToken).  When 
+the token is cancelled, 
+a [TaskCanceledException](xref:System.Threading.Tasks.TaskCanceledException) 
+will be `thrown`.
+
+Here's a contrived example ([unit test](https://github.com/richardschneider/net-ipfs-api/blob/cancellation/test/CoreApi/CancellationTest.cs)) 
+that forces the getting of info on the local IPFS server to be cancelled
+
+```csharp
+var cts = new CancellationTokenSource(500);
+try
+{
+	await Task.Delay(1000);
+	var peer = await ipfs.IdAsync(cts.Token);
+	Assert.Fail("Did not throw TaskCanceledException");
+}
+catch (TaskCanceledException)
+{
+	return;
+}
+```
+
+See also [Task Cancellation](https://docs.microsoft.com/en-us/dotnet/standard/parallel-programming/task-cancellation)

doc/articles/client.md

@@ -0,0 +1,33 @@
+# Accessing IPFS
+
+IPFS is a distributed peer to peer system.  There is no central server!  Typically, each machine (peer) runs 
+a [daemon](daemon.md) that communicates with other peers.
+
+The [IpfsClient](xref:Ipfs.Api.IpfsClient) provides a simple way for your program to access the daemon 
+via the [IPFS HTTP API](https://docs.ipfs.io/reference/api/http/) protocol. The client 
+should be used as a shared object in your program, much like [HttpClient](xref:System.Net.Http.HttpClient).  It is 
+thread safe (re-entrant) and conserves sockets and TCP connections when only one instance is used.
+
+```csharp
+public class Program
+{
+  static readonly IpfsClient ipfs = new IpfsClient();
+  public async Task Main(string[] args) 
+  {
+	// Get the Peer info of the daemon
+	var peer = await ipfs.IdAsync();
+  }
+}
+```
+
+## Locating the daemon
+
+By default the client looks for a deamon at `http://localhost:5001`.  This can be overriden by either 
+setting the environment variable [IpfsHttpUrl](envvars.md) or initialising the client with an URL.
+
+```csharp
+// js-ipfs likes this address
+static readonly IpfsClient ipfs = new IpfsClient("http://127.0.0.1:5002");
+```
+
+

doc/articles/daemon.md

@@ -0,0 +1,20 @@
+# IPFS Daemon
+
+The IPFS daemon is a service that runs on a machine and allows access to other peers on the network. This 
+is what the [IPFS client](client.md) manages.
+
+## Installing
+
+The authoritive documentmenation is at [https://docs.ipfs.io/introduction/install/](https://docs.ipfs.io/introduction/install/) which 
+describes the `go-ipfs` implementation. 
+There is also [js-ipfs](https://docs.ipfs.io/reference/js/overview/) for NodeJS fans.
+
+### Windows
+
+For Windows using [chocolatey](https://chocolatey.org/)
+
+```
+> choco install go-ipfs
+> ipfs init
+> ipfs daemon
+```

doc/articles/envvars.md

@@ -1,8 +1,8 @@
 # Environment variables
 
 The following [environment variables](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682653.aspx) 
-are used  to control the behaviour of the library
+are used  to control the behaviour of the library.  They override the default value.
 
 | Name | Description |
 | --- | --- |
-| IpfsHttpUrl | The default URL to the IPFS HTTP API server. See [DefaultApiUri](xref:Ipfs.Api.IpfsClient.DefaultApiUri) for more details. |
+| IpfsHttpUrl | The [default URL](xref:Ipfs.Api.IpfsClient.DefaultApiUri) to the IPFS HTTP API [daemon](daemon.md).

doc/articles/toc.yml

@@ -1,9 +1,10 @@
 - name: Introduction
   href: intro.md
+- name: Accessing IPFS
+  href: client.md
 - name: Asynchronous I/O
   href: async.md
-  items:
-    - name: Cancellation
-      href: cancellation.md
 - name: Environment variables
-  href: envvars.md
+  href: envvars.md
+- name: IPFS daemon
+  href: daemon.md