From 5f660c33436e02d5faeb0c5528239fe31a4acda7 Mon Sep 17 00:00:00 2001 From: mort5161 Date: Tue, 11 Nov 2014 17:44:02 -0800 Subject: [PATCH] Doc comments --- src/NmeaParser.Shared/BufferedStreamDevice.cs | 85 ++++++++++++++++++- src/NmeaParser.Shared/NmeaDevice.cs | 57 +++++++++++++ src/NmeaParser.Shared/NmeaFileDevice.cs | 6 +- src/NmeaParser.Shared/StreamDevice.cs | 13 +++ src/NmeaParser.WinDesktop/SerialPortDevice.cs | 13 +++ src/NmeaParser.WinStore/BluetoothDevice.cs | 13 +++ 6 files changed, 184 insertions(+), 3 deletions(-) diff --git a/src/NmeaParser.Shared/BufferedStreamDevice.cs b/src/NmeaParser.Shared/BufferedStreamDevice.cs index 1731d4b..829ccae 100644 --- a/src/NmeaParser.Shared/BufferedStreamDevice.cs +++ b/src/NmeaParser.Shared/BufferedStreamDevice.cs @@ -41,8 +41,16 @@ namespace NmeaParser m_readSpeed = readSpeed; } + /// + /// Gets the stream to perform buffer reads on. + /// + /// protected abstract Task GetStreamAsync(); + /// + /// Opens the stream asynchronous. + /// + /// protected sealed async override Task OpenStreamAsync() { var stream = await GetStreamAsync(); @@ -51,6 +59,11 @@ namespace NmeaParser return m_stream; } + /// + /// Closes the stream asynchronous. + /// + /// The stream. + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { m_stream.Dispose(); @@ -65,6 +78,11 @@ namespace NmeaParser byte[] buffer = new byte[0]; System.Threading.Timer timer; object lockObj = new object(); + /// + /// Initializes a new instance of the class. + /// + /// The stream. + /// The read speed. public BufferedStream(StreamReader stream, int readSpeed) { m_sr = stream; @@ -86,13 +104,46 @@ namespace NmeaParser buffer = newBuffer; } } + /// + /// Gets a value indicating whether this instance can read. + /// + /// + /// true if this instance can read; otherwise, false. + /// public override bool CanRead { get { return true; } } + /// + /// Gets a value indicating whether this instance can seek. + /// + /// + /// true if this instance can seek; otherwise, false. + /// public override bool CanSeek { get { return false; } } + /// + /// Gets a value indicating whether this instance can write. + /// + /// + /// true if this instance can write; otherwise, false. + /// public override bool CanWrite { get { return false; } } + /// + /// Flushes this instance. + /// public override void Flush() { } - + /// + /// Gets the length. + /// + /// + /// The length. + /// public override long Length { get { return m_sr.BaseStream.Length; } } + /// + /// Gets or sets the position. + /// + /// + /// The position. + /// + /// public override long Position { get { return m_sr.BaseStream.Position; } @@ -101,7 +152,13 @@ namespace NmeaParser throw new NotSupportedException(); } } - + /// + /// Reads the specified buffer. + /// + /// The buffer. + /// The offset. + /// The count. + /// public override int Read(byte[] buffer, int offset, int count) { lock (lockObj) @@ -124,20 +181,44 @@ namespace NmeaParser } } + /// + /// Seeks the specified offset. + /// + /// The offset. + /// The origin. + /// + /// public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(); } + /// + /// Sets the length. + /// + /// The value. + /// public override void SetLength(long value) { throw new NotSupportedException(); } + /// + /// Writes the specified buffer. + /// + /// The buffer. + /// The offset. + /// The count. + /// public override void Write(byte[] buffer, int offset, int count) { throw new NotSupportedException(); } + + /// + /// Releases unmanaged and - optionally - managed resources. + /// + /// true to release both managed and unmanaged resources; false to release only unmanaged resources. protected override void Dispose(bool disposing) { base.Dispose(disposing); diff --git a/src/NmeaParser.Shared/NmeaDevice.cs b/src/NmeaParser.Shared/NmeaDevice.cs index af37abb..1a7b312 100644 --- a/src/NmeaParser.Shared/NmeaDevice.cs +++ b/src/NmeaParser.Shared/NmeaDevice.cs @@ -35,9 +35,16 @@ namespace NmeaParser System.Threading.CancellationTokenSource m_cts; TaskCompletionSource closeTask; + /// + /// Initializes a new instance of the class. + /// protected NmeaDevice() { } + /// + /// Opens the device connection. + /// + /// public async Task OpenAsync() { lock (m_lockObject) @@ -80,7 +87,15 @@ namespace NmeaParser }); } + /// + /// Creates the stream the NmeaDevice is working on top off. + /// + /// protected abstract Task OpenStreamAsync(); + /// + /// Closes the device. + /// + /// public async Task CloseAsync() { if (m_cts != null) @@ -97,6 +112,11 @@ namespace NmeaParser lock (m_lockObject) IsOpen = false; } + /// + /// Closes the stream the NmeaDevice is working on top off. + /// + /// The stream. + /// protected abstract Task CloseStreamAsync(Stream stream); private void OnData(byte[] data) @@ -171,12 +191,22 @@ namespace NmeaParser private Dictionary> MultiPartMessageCache = new Dictionary>(); + /// + /// Occurs when an NMEA message is received. + /// public event EventHandler MessageReceived; + /// + /// Releases unmanaged and - optionally - managed resources. + /// public void Dispose() { Dispose(true); } + /// + /// Releases unmanaged and - optionally - managed resources. + /// + /// true to release both managed and unmanaged resources; false to release only unmanaged resources. protected virtual void Dispose(bool force) { if (m_stream != null) @@ -191,16 +221,43 @@ namespace NmeaParser } } + /// + /// Gets a value indicating whether this device is open. + /// + /// + /// true if this instance is open; otherwise, false. + /// public bool IsOpen { get; private set; } } + /// + /// Event argument for the + /// public sealed class NmeaMessageReceivedEventArgs : EventArgs { internal NmeaMessageReceivedEventArgs(Nmea.NmeaMessage message) { Message = message; } + /// + /// Gets the nmea message. + /// + /// + /// The nmea message. + /// public Nmea.NmeaMessage Message { get; private set; } + /// + /// Gets a value indicating whether this instance is a multi part message. + /// + /// + /// true if this instance is multi part; otherwise, false. + /// public bool IsMultiPart { get; internal set; } + /// + /// Gets the message parts if this is a multi-part message and all message parts has been received. + /// + /// + /// The message parts. + /// public Nmea.NmeaMessage[] MessageParts { get; internal set; } } } diff --git a/src/NmeaParser.Shared/NmeaFileDevice.cs b/src/NmeaParser.Shared/NmeaFileDevice.cs index d3abab5..9b72e76 100644 --- a/src/NmeaParser.Shared/NmeaFileDevice.cs +++ b/src/NmeaParser.Shared/NmeaFileDevice.cs @@ -35,7 +35,7 @@ namespace NmeaParser #endif int m_readSpeed; /// - /// + /// Initializes a new instance of the class. /// /// /// The time to wait between each line being read in milliseconds @@ -48,6 +48,10 @@ namespace NmeaParser m_filename = filename; m_readSpeed = readSpeed; } + /// + /// Gets the stream to perform buffer reads on. + /// + /// protected override Task GetStreamAsync() { #if NETFX_CORE diff --git a/src/NmeaParser.Shared/StreamDevice.cs b/src/NmeaParser.Shared/StreamDevice.cs index 7e211ea..9592c99 100644 --- a/src/NmeaParser.Shared/StreamDevice.cs +++ b/src/NmeaParser.Shared/StreamDevice.cs @@ -28,16 +28,29 @@ namespace NmeaParser public class StreamDevice : NmeaDevice { System.IO.Stream m_stream; + /// + /// Initializes a new instance of the class. + /// + /// The stream. public StreamDevice(Stream stream) : base() { m_stream = stream; } + /// + /// Opens the stream asynchronous. + /// + /// protected override Task OpenStreamAsync() { return Task.FromResult(m_stream); } + /// + /// Closes the stream asynchronous. + /// + /// The stream. + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { return Task.FromResult(true); //do nothing diff --git a/src/NmeaParser.WinDesktop/SerialPortDevice.cs b/src/NmeaParser.WinDesktop/SerialPortDevice.cs index 01a3cd2..1f0f386 100644 --- a/src/NmeaParser.WinDesktop/SerialPortDevice.cs +++ b/src/NmeaParser.WinDesktop/SerialPortDevice.cs @@ -30,17 +30,30 @@ namespace NmeaParser { private System.IO.Ports.SerialPort m_port; + /// + /// Initializes a new instance of the class. + /// + /// The serial port. public SerialPortDevice(System.IO.Ports.SerialPort port) { m_port = port; } + /// + /// Creates the stream the NmeaDevice is working on top off. + /// + /// protected override Task OpenStreamAsync() { m_port.Open(); return Task.FromResult(m_port.BaseStream); } + /// + /// Closes the stream the NmeaDevice is working on top off. + /// + /// The stream. + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { m_port.Close(); diff --git a/src/NmeaParser.WinStore/BluetoothDevice.cs b/src/NmeaParser.WinStore/BluetoothDevice.cs index ac51902..5c1878b 100644 --- a/src/NmeaParser.WinStore/BluetoothDevice.cs +++ b/src/NmeaParser.WinStore/BluetoothDevice.cs @@ -40,11 +40,19 @@ namespace NmeaParser private BTDevice m_device; private StreamSocket m_socket; + /// + /// Initializes a new instance of the class. + /// + /// The device. public BluetoothDevice(BTDevice device) { m_device = device; } + /// + /// Creates the stream the NmeaDevice is working on top off. + /// + /// protected override async Task OpenStreamAsync() { var socket = new Windows.Networking.Sockets.StreamSocket(); @@ -59,6 +67,11 @@ namespace NmeaParser return socket.InputStream.AsStreamForRead(); } + /// + /// Closes the stream the NmeaDevice is working on top off. + /// + /// The stream. + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { stream.Dispose();