Add more api ref doc describing how to use devices

.gitignore

@@ -113,3 +113,4 @@ project.lock.json
 src/.vs/
 artifacts
 .tools
+docs/memberpage.2.48.1

docs/BuildDoc.cmd

@@ -21,7 +21,6 @@ mkdir %~dp0../artifacts/docs/api
 %~dp0..\.tools\omd\generateomd /source=%~dp0../src/NmeaParser /output=%~dp0../artifacts/docs/api/omd.html /preprocessors=NETSTANDARD1_4;NETSTANDARD
 
 %~dp0..\.tools\nuget install memberpage -Version 2.48.1 -OutputDirectory %~dp0
-PAUSE
 REM Build the output site (HTML) from the generated metadata and input files (uses configuration in docfx.json in this folder)
 %DocFxFolder%\v%DocFXVersion%\docfx.exe %~dp0\docfx.json
 ECHO Fixing API Reference Links

src/NmeaParser/BluetoothDevice.Android.cs

@@ -25,6 +25,20 @@ namespace NmeaParser
     /// <summary>
     /// A Bluetooth NMEA device
     /// </summary>
+    /// <remarks>
+    /// To use this device, ensure you have the necessary permissions in the <c>AndroidManifest.xml</c> file:
+    /// <code lang="xml">
+    /// ```xml
+    /// 	&lt;uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    /// 	&lt;uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    /// 	&lt;uses-permission android:name="android.permission.BLUETOOTH" />
+    /// ```
+    /// </code>
+    /// <para>
+    /// Next see MainActivity.cs in the Android sample as a reference:
+    /// https://github.com/dotMorten/NmeaParser/blob/master/src/SampleApp.Droid/MainActivity.cs
+    /// </para>
+    /// </remarks>
     public class BluetoothDevice : NmeaDevice
     {
         private static Java.Util.UUID SERIAL_UUID = Java.Util.UUID.FromString("00001101-0000-1000-8000-00805F9B34FB");

src/NmeaParser/BluetoothDevice.UWP.cs

@@ -31,6 +31,42 @@ namespace NmeaParser
     /// <summary>
     /// A Bluetooth NMEA device
     /// </summary>
+    /// <remarks>
+    /// To use the NMEA Parser against a bluetooth device in a Universal App,
+    /// ensure the bluetooth capability is enabled by opening <c>package.appxmanifest</c> in a text editor,
+    /// and add the following to the <c>&lt;Capabilities></c> section:
+    /// <code lang="xml">
+    /// &lt;DeviceCapability Name="bluetooth.rfcomm">
+    ///   &lt;Device Id="any">
+    ///     &lt;Function Type="name:serialPort" />
+    ///   &lt;/Device>
+    /// &lt;/DeviceCapability>
+    /// </code>
+    /// <para>
+    /// See more here on bluetooth device capabilities in UWP Apps: https://docs.microsoft.com/en-us/uwp/schemas/appxpackage/how-to-specify-device-capabilities-for-bluetooth
+    /// </para>
+    /// <para>Make sure your Bluetooth device is paired with your Windows Device.</para>
+    /// <code lang="cs">
+    /// //Get list of devices
+    ///     string serialDeviceType = RfcommDeviceService.GetDeviceSelector(RfcommServiceId.SerialPort);
+    ///     var devices = await DeviceInformation.FindAllAsync(serialDeviceType);
+    ///     //Select device by name (in this case TruePulse 360B Laser Range Finder)
+    ///     var TruePulse360B = devices.Where(t => t.Name.StartsWith("TP360B-")).FirstOrDefault();
+    ///     //Get service
+    ///     RfcommDeviceService rfcommService = await RfcommDeviceService.FromIdAsync(TruePulse360B.Id);
+    /// if (rfcommService != null)
+    /// {
+    /// 	var rangeFinder = new NmeaParser.BluetoothDevice(rfcommService);
+    ///     rangeFinder.MessageReceived += device_NmeaMessageReceived;
+    /// 	await rangeFinder.OpenAsync();
+    /// }
+    /// ...
+    /// private void device_NmeaMessageReceived(object sender, NmeaParser.NmeaMessageReceivedEventArgs args)
+    /// {
+    ///     // called when a message is received
+    /// }
+    /// </code>
+    /// </remarks>
     public class BluetoothDevice : NmeaDevice
     {
         private Windows.Devices.Bluetooth.Rfcomm.RfcommDeviceService? m_deviceService;

src/NmeaParser/SerialPortDevice.Desktop.cs

@@ -25,6 +25,23 @@ namespace NmeaParser
     /// <summary>
     /// A Serial Port NMEA device
     /// </summary>
+    /// <remarks>
+    /// Below is an example of connecting to a serial port using .NET Core or .NET Framework.
+    /// Make sure you choose the correct port name and baud rate.
+    /// <code lang="cs">
+    /// string portname = "COM3"; // Change to match the name of the port your device is connected to
+    /// int baudrate = 9600; // Change to the baud rate your device communicates at (usually specified in the manual)
+    /// var port = new System.IO.Ports.SerialPort(portname, baudrate);
+    /// var device = new NmeaParser.SerialPortDevice(port);
+    /// device.MessageReceived += OnNmeaMessageReceived;
+    /// device.OpenAsync();
+    /// ...
+    /// private void OnNmeaMessageReceived(NmeaParser.NmeaDevice sender, NmeaParser.NmeaMessageReceivedEventArgs args)
+    /// {
+    ///    // called when a message is received
+    /// }
+    /// </code>
+    /// </remarks>
     public class SerialPortDevice : NmeaDevice
     {
         /// <summary>

src/NmeaParser/SerialPortDevice.UWP.cs

@@ -23,10 +23,43 @@ using Windows.Devices.SerialCommunication;
 using System.Runtime.InteropServices.WindowsRuntime;
 
 namespace NmeaParser
-{
+{
     /// <summary>
     /// A Serial Port NMEA device
     /// </summary>
+    /// <remarks>
+    /// <para>
+    /// To use the NMEA Parser against a serial device in a Windows 10 Universal app, ensure the serial device capability is enabled by opening package.appxmanifest in a text editor, and add the following to the <c>&lt;Capabilities></c> section:
+    /// </para>
+    /// <code lang="xml">
+    ///    &lt;DeviceCapability Name="serialcommunication"> 
+    ///      &lt;Device Id="any">
+    ///        &lt;Function Type="name:serialPort" /> 
+    ///      &lt;/Device> 
+    ///    &lt;/DeviceCapability>
+    /// </code>
+    /// <code lang="cs">
+    /// var selector = SerialDevice.GetDeviceSelector("COM3"); //Get the serial port on port '3'
+    /// var devices = await DeviceInformation.FindAllAsync(selector);
+    /// if(devices.Any()) //if the device is found
+    /// {
+    /// 	var deviceInfo = devices.First();
+    ///     var serialDevice = await SerialDevice.FromIdAsync(deviceInfo.Id);
+    ///     //Set up serial device according to device specifications:
+    ///     //This might differ from device to device
+    ///     serialDevice.BaudRate = 4800;
+    /// 	serialDevice.DataBits = 8;
+    /// 	serialDevice.Parity = SerialParity.None;
+    /// 	var device = new NmeaParser.SerialPortDevice(serialDevice);
+    ///     device.MessageReceived += device_NmeaMessageReceived;
+    /// }
+    /// ...
+    /// private void device_NmeaMessageReceived(NmeaParser.NmeaDevice sender, NmeaMessageReceivedEventArgs args)
+    /// {
+    ///     // called when a message is received
+    /// }
+    /// </code>
+    /// </remarks>
     public class SerialPortDevice : NmeaDevice
     {
         private SerialDevice m_port;