docs: improve

richardschneider · Oct 12, 2018 · edfe3c7 · edfe3c7
1 parent db2345d
commit edfe3c7
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 11 deletions.
diff --git a/doc/articles/intro.md b/doc/articles/intro.md
@@ -8,12 +8,12 @@ It conforms to
 The above RFCs are commonly referred to as [Bonjour](https://developer.apple.com/bonjour/) or 
 [Zero Config](http://www.zeroconf.org/).
 
-The [MulticastService](xref:Makaretu.Dns.MulticastService) is used to send [DNS](https://en.wikipedia.org/wiki/Domain_Name_System)
-[queries](xref:Makaretu.Dns.MulticastService.SendQuery) and 
-[answers](xref:Makaretu.Dns.MulticastService.SendAnswer) over the link local network.
+The [MulticastService](xref:Makaretu.Dns.MulticastService) is used to send DNS
+[queries](xref:Makaretu.Dns.MulticastService.SendQuery*) and 
+[answers](xref:Makaretu.Dns.MulticastService.SendAnswer*) over the link local network.
 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.
 
 To broadcast a service, simply create a [ServiceProfile](xref:Makaretu.Dns.ServiceProfile) 
-and then [Advertise](xref:Makaretu.Dns.ServiceDiscovery.Advertise) it.  Any queries for the service or 
+and then [Advertise](xref:Makaretu.Dns.ServiceDiscovery.Advertise*) it.  Any queries for the service or 
 service instance will be answered with information from the profile.
diff --git a/src/ServiceDiscovery.cs b/src/ServiceDiscovery.cs
@@ -55,6 +55,9 @@ public ServiceDiscovery(MulticastService mdns)
         /// <summary>
         ///   Gets the multicasting service.
         /// </summary>
+        /// <value>
+        ///   Is used to send and recieve multicast <see cref="Message">DNS messages</see>.
+        /// </value>
         public MulticastService Mdns { get; private set; }
 
         /// <summary>

diff --git a/src/ServiceInstanceDiscoveryEventArgs.cs b/src/ServiceInstanceDiscoveryEventArgs.cs
@@ -13,6 +13,10 @@ public class ServiceInstanceDiscoveryEventArgs : MessageEventArgs
         /// <summary>
         ///   The fully qualified name of the service instance.
         /// </summary>
+        /// <value>
+        ///   Typically of the form "<i>instance</i>._<i>service</i>._tcp.local".
+        /// </value>
+        /// <seealso cref="ServiceProfile.FullyQualifiedName"/>
         public string ServiceInstanceName { get; set; }
     }
 }

diff --git a/src/ServiceProfile.cs b/src/ServiceProfile.cs
@@ -80,10 +80,10 @@ public ServiceProfile(string instanceName, string serviceName, ushort port, IEnu
         }
 
         /// <summary>
-        ///   The domain name of the service.
+        ///   The top level domain (TLD) name of the service.
         /// </summary>
         /// <value>
-        ///   Defaults to "local".
+        ///   Always "local".
         /// </value>
         public string Domain { get; } = "local";
 
@@ -115,7 +115,7 @@ public ServiceProfile(string instanceName, string serviceName, ushort port, IEnu
         ///   The service name and domain.
         /// </summary>
         /// <value>
-        ///   <see cref="ServiceName"/>.<see cref="Domain"/>
+        ///   Typically of the form "_<i>service</i>._tcp.local".
         /// </value>
         public string QualifiedServiceName => $"{ServiceName}.{Domain}";
 
@@ -139,18 +139,23 @@ public ServiceProfile(string instanceName, string serviceName, ushort port, IEnu
         /// <summary>
         ///   DNS resource records that are used to locate the service instance.
         /// </summary>
+        /// <value>
+        ///   More infomation about the service.
+        /// </value>
         /// <remarks>
         ///   All records should have the <see cref="ResourceRecord.Name"/> equal
-        ///   to the <see cref="FullyQualifiedName"/>.
+        ///   to the <see cref="FullyQualifiedName"/> or the <see cref="HostName"/>.
         ///   <para>
-        ///   At a minimum the SRV and TXT records must be present.  Typically A/AAAA
-        ///   records are also present.
+        ///   At a minimum the <see cref="SRVRecord"/> and <see cref="TXTRecord"/>
+        ///   records must be present.
+        ///   Typically <see cref="AddressRecord">address records</see>
+        ///   are also present and are associaed with <see cref="HostName"/>.
         ///   </para>
         /// </remarks>
         public List<ResourceRecord> Resources { get; set; } = new List<ResourceRecord>();
 
         /// <summary>
-        ///   Add a property of the service to the TXT record.
+        ///   Add a property of the service to the <see cref="TXTRecord"/>.
         /// </summary>
         /// <param name="key">
         ///   The name of the property.