doc(): first pass

README.md

@@ -23,7 +23,7 @@ A DNS client that can fetch more than `A` and `AAAA` resource records.
 
 Published releases are available on [NuGet](https://www.nuget.org/packages/Makaretu.Dns.Unicast/).  To install, run the following command in the [Package Manager Console](https://docs.nuget.org/docs/start-here/using-the-package-manager-console).
 
-    PM> Install-Package Makaretu.Mdns
+    PM> Install-Package Makaretu.Dns.Unicast
 
 ## Usage
 

doc/articles/async.md

@@ -0,0 +1,17 @@
+# Asynchronous I/O
+
+All requests to the DNS 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
+
+```csharp
+Message response = await DnsClient.QueryAsync(...);
+```
+
+# Synchronous I/O
+If a synchronous operation is required, then this can work
+
+```csharp
+Message response = DnsClient.QueryAsync(...).Result;
+```

doc/articles/cancellation.md

@@ -0,0 +1,25 @@
+# Cancelling a request
+
+All requests to the DNS 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 unit test that forces the query to be cancelled
+
+```csharp
+var cts = new CancellationTokenSource(500);
+try
+{
+	await Task.Delay(400);
+	var response = await DnsClient.QueryAsync(..., 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/intro.md

@@ -1,4 +1,27 @@
-A simple Multicast Domain Name Service based on [RFC 6762](https://tools.ietf.org/html/rfc6762).  The source code is on [GitHub](https://github.com/richardschneider/net-mdns) and the package is published on [NuGet](https://www.nuget.org/packages/Makaretu.Dns.Multicast).
+# DNS Client
 
-The [MulticastService](xref:Makaretu.Dns.MulticastService) is used to send [queries](xref:Makaretu.Dns.MulticastService.SendQuery) and [answers](xref:Makaretu.Dns.MulticastService.SendAnswer).  It also listens for DNS [Messages](xref:Makaretu.Dns.Message) and raises either the [QueryReceived](xref:Makaretu.Dns.MulticastService.QueryReceived) or [AnswerReceived](xref:Makaretu.Dns.MulticastService.AnswerReceived) event.
+A simple Unicast DNS client that communicates with a DNS server over UPD and TCP. 
+The source code is on [GitHub](https://github.com/richardschneider/net-udns) and the package is published on [NuGet](https://www.nuget.org/packages/Makaretu.Dns.Unicast).
+
+[DnsClient](xref:Makaretu.Dns.DnsClient) is used to send a [Message](xref:Makaretu.Dns.Message) to a DNS server and receive a response.  
+
+## Usage
+
+Get all the TXT strings assoicated with "ipfs.io"
+
+```csharp
+using Makaretu.Dns;
+
+var response = await DnsClient.QueryAsync("ipfs.io", DnsType.TXT);
+var strings = response.Answers
+    .OfType<TXTRecord>()
+    .SelectMany(txt => txt.Strings);
+foreach (var s in strings)
+    Console.WriteLine(s);
+```
+
+Produces the output
+```
+dnslink=/ipfs/QmYNQJoKGNHTpPxCBPh9KkDpaExgd2duMa3aF6ytMpHdao
+```
 

doc/articles/server.md

@@ -0,0 +1,17 @@
+# Finding a DNS server
+
+## Default
+
+Normally the OS network interfaces are queried for the DNS servers; see [GetServers](xref:Makaretu.Dns.DnsClient.GetServers) for the details.
+
+## Specific
+
+To specify the servers, set the [DnsClient.Servers](xref:Makaretu.Dns.DnsClient.Servers) property
+
+```csharp
+DnsClient.Servers = new IPAddress[] 
+{
+    IPAddress.Parse("8.8.8.8"),
+    IPAddress.Parse("2001:4860:4860::8888")
+}; 
+```

doc/articles/toc.yml

@@ -1,4 +1,11 @@
 - name: Introduction
   href: intro.md
+- name: Finding a server
+  href: server.md
+- name: Asynchronous I/O
+  href: async.md
+  items:
+    - name: Cancellation
+      href: cancellation.md
 - name: Class Reference
   href: ../api/Makaretu.Dns.yml

doc/docfx.json

@@ -71,7 +71,7 @@
       "https://richardschneider.github.io/net-dns/xrefmap.yml"
     ],
     "globalMetadata": {
-      "_appTitle": "Multicast DNS documentation",
+      "_appTitle": "DNS Client",
       "_appFooter": "Generated by DocFX"
     },
     "dest": "_site",

doc/index.md

@@ -1,8 +1,8 @@
-# Multicast DNS
+# DNS Client
 
-A simple Multicast Domain Name Service based on [RFC 6762](https://tools.ietf.org/html/rfc6762).  Can be used as both a client (sending queries) or a server (responding to queries).
+A simple Unicast DNS client that communicates with a DNS server over UPD and TCP.
 
-The source code is on [GitHub](https://github.com/richardschneider/net-mdns) and the package is published on [NuGet](https://www.nuget.org/packages/Makaretu.Dns.Multicast).
+The source code is on [GitHub](https://github.com/richardschneider/net-udns) and the package is published on [NuGet](https://www.nuget.org/packages/Makaretu.Dns.Unicast).
 
 - [Articles](articles/intro.md) on using Multicast DNS.
 - [Documentation](api/Makaretu.Dns.yml) describes the classes in detail  

src/Udns.csproj

@@ -15,7 +15,7 @@
     <PackageId>Makaretu.Dns.Unicast</PackageId>
     <Authors>Richard Schneider</Authors>
     <Title>Unicast DNS client</Title>
-    <Description>A simple Unicast DNS client for TCP and UDP</Description>
+    <Description>A simple Unicast DNS client for UPD and TCP</Description>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
     <PackageReleaseNotes></PackageReleaseNotes>
     <Copyright>© 2018 Richard Schneider</Copyright>