From d33430b582e1fb8a8ac3c068ba591e40b99f52e0 Mon Sep 17 00:00:00 2001 From: Morten Nielsen Date: Sat, 1 Feb 2020 16:37:42 -0800 Subject: [PATCH] doc comment improvements --- src/NmeaParser/BluetoothDevice.Android.cs | 13 +-- src/NmeaParser/BluetoothDevice.UWP.cs | 13 +-- src/NmeaParser/BufferedStreamDevice.cs | 94 +++++----------------- src/NmeaParser/Nmea/NmeaMessage.cs | 10 +-- src/NmeaParser/NmeaDevice.cs | 21 ++--- src/NmeaParser/NmeaFileDevice.cs | 5 +- src/NmeaParser/SerialPortDevice.Desktop.cs | 11 +-- src/NmeaParser/SerialPortDevice.UWP.cs | 11 +-- src/NmeaParser/StreamDevice.cs | 11 +-- 9 files changed, 47 insertions(+), 142 deletions(-) diff --git a/src/NmeaParser/BluetoothDevice.Android.cs b/src/NmeaParser/BluetoothDevice.Android.cs index 12c893a..bd61a62 100644 --- a/src/NmeaParser/BluetoothDevice.Android.cs +++ b/src/NmeaParser/BluetoothDevice.Android.cs @@ -34,7 +34,7 @@ namespace NmeaParser /// /// Gets a list of bluetooth devices that supports serial communication /// - /// + /// A set of bluetooth devices available that supports serial connections public static IEnumerable GetBluetoothSerialDevices() { var adapter = Android.Bluetooth.BluetoothAdapter.DefaultAdapter; @@ -54,10 +54,7 @@ namespace NmeaParser m_device = device ?? throw new ArgumentNullException(nameof(device)); } - /// - /// Creates the stream the NmeaDevice is working on top off. - /// - /// + /// protected override Task OpenStreamAsync() { var adapter = Android.Bluetooth.BluetoothAdapter.DefaultAdapter; @@ -70,11 +67,7 @@ namespace NmeaParser return Task.FromResult(socket.InputStream); } - /// - /// Closes the stream the NmeaDevice is working on top off. - /// - /// The stream. - /// + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { if (stream == null) diff --git a/src/NmeaParser/BluetoothDevice.UWP.cs b/src/NmeaParser/BluetoothDevice.UWP.cs index e752eea..5f5025f 100644 --- a/src/NmeaParser/BluetoothDevice.UWP.cs +++ b/src/NmeaParser/BluetoothDevice.UWP.cs @@ -42,7 +42,7 @@ namespace NmeaParser /// /// Gets a list of bluetooth devices that supports serial communication /// - /// + /// A set of bluetooth devices available that supports serial connections public static async Task> GetBluetoothSerialDevicesAsync() { string serialDeviceType = RfcommDeviceService.GetDeviceSelector(RfcommServiceId.SerialPort); @@ -83,10 +83,7 @@ namespace NmeaParser base.Dispose(disposing); } - /// - /// Creates the stream the NmeaDevice is working on top off. - /// - /// + /// protected override async Task OpenStreamAsync() { var socket = new Windows.Networking.Sockets.StreamSocket(); @@ -120,11 +117,7 @@ namespace NmeaParser public override void Write(byte[] buffer, int offset, int count) => throw new NotSupportedException(); } - /// - /// Closes the stream the NmeaDevice is working on top off. - /// - /// The stream. - /// + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { if(m_socket == null) diff --git a/src/NmeaParser/BufferedStreamDevice.cs b/src/NmeaParser/BufferedStreamDevice.cs index 09decc0..fc5c0da 100644 --- a/src/NmeaParser/BufferedStreamDevice.cs +++ b/src/NmeaParser/BufferedStreamDevice.cs @@ -48,14 +48,11 @@ namespace NmeaParser /// /// Gets the stream to perform buffer reads on. /// - /// + /// The opened data stream. [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")] protected abstract Task GetStreamAsync(); - /// - /// Opens the stream asynchronous. - /// - /// + /// protected sealed async override Task OpenStreamAsync() { var stream = await GetStreamAsync(); @@ -64,11 +61,7 @@ namespace NmeaParser return m_stream; } - /// - /// Closes the stream asynchronous. - /// - /// The stream. - /// + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { m_stream?.Dispose(); @@ -135,46 +128,23 @@ namespace NmeaParser m_sr.BaseStream.Seek(0, SeekOrigin.Begin); //start over return m_sr.ReadLine() + '\n'; } - /// - /// 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; } @@ -183,13 +153,8 @@ 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) @@ -212,44 +177,25 @@ 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 to the device. - /// - /// 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/Nmea/NmeaMessage.cs b/src/NmeaParser/Nmea/NmeaMessage.cs index 099959f..2df5b5b 100644 --- a/src/NmeaParser/Nmea/NmeaMessage.cs +++ b/src/NmeaParser/Nmea/NmeaMessage.cs @@ -137,7 +137,7 @@ namespace NmeaParser.Messages /// /// The NMEA message string. /// The previously received message (only used if parsing multi-sentence messages) - /// + /// The nmea message that was parsed. /// /// Invalid nmea message: Missing starting character '$' /// or checksum failure @@ -199,6 +199,7 @@ namespace NmeaParser.Messages /// /// Gets the NMEA type id for the message. /// + /// The 5 character string that identifies the message type public string MessageType { get; } /// @@ -211,12 +212,7 @@ namespace NmeaParser.Messages /// public bool IsProprietary => MessageType[0] == 'P'; //Appendix B - /// - /// Returns a that represents this instance. - /// - /// - /// A that represents this instance. - /// + /// public override string ToString() { return string.Format(CultureInfo.InvariantCulture, "${0},{1}*{2:X2}", MessageType, string.Join(",", MessageParts), Checksum); diff --git a/src/NmeaParser/NmeaDevice.cs b/src/NmeaParser/NmeaDevice.cs index d75f432..c65f493 100644 --- a/src/NmeaParser/NmeaDevice.cs +++ b/src/NmeaParser/NmeaDevice.cs @@ -42,10 +42,10 @@ namespace NmeaParser { } - /// - /// Opens the device connection. - /// - /// + /// + /// Creates and opens the stream the will be working on top off. + /// + /// A task that represents the asynchronous action. public async Task OpenAsync() { lock (m_lockObject) @@ -112,15 +112,16 @@ namespace NmeaParser } /// - /// Creates the stream the NmeaDevice is working on top off. + /// Creates and opens the stream the NmeaDevice is working on top off. /// - /// + /// The opened data stream. + /// protected abstract Task OpenStreamAsync(); /// /// Closes the device. /// - /// + /// A task that represents the asynchronous action. public async Task CloseAsync() { if (m_cts != null) @@ -144,8 +145,9 @@ namespace NmeaParser /// /// Closes the stream the NmeaDevice is working on top off. /// - /// The stream. - /// + /// The stream to be closed. + /// A task that represents the asynchronous action. + /// protected abstract Task CloseStreamAsync(Stream stream); private void OnData(byte[] data) @@ -170,7 +172,6 @@ namespace NmeaParser ProcessMessage(line); } - private IMultiSentenceMessage? _lastMultiMessage; [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1031:DoNotCatchGeneralExceptionTypes", Justification="Must silently handle invalid/corrupt input")] diff --git a/src/NmeaParser/NmeaFileDevice.cs b/src/NmeaParser/NmeaFileDevice.cs index 48bdc88..cf19ed4 100644 --- a/src/NmeaParser/NmeaFileDevice.cs +++ b/src/NmeaParser/NmeaFileDevice.cs @@ -84,10 +84,7 @@ namespace NmeaParser } } - /// - /// Gets the stream to perform buffer reads on. - /// - /// + /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Reliability", "CA2000:Dispose objects before losing scope")] protected override Task GetStreamAsync() { diff --git a/src/NmeaParser/SerialPortDevice.Desktop.cs b/src/NmeaParser/SerialPortDevice.Desktop.cs index d1807cb..bb4e68c 100644 --- a/src/NmeaParser/SerialPortDevice.Desktop.cs +++ b/src/NmeaParser/SerialPortDevice.Desktop.cs @@ -44,10 +44,7 @@ namespace NmeaParser /// public System.IO.Ports.SerialPort Port { get; } - /// - /// Creates the stream the NmeaDevice is working on top off. - /// - /// + /// protected override Task OpenStreamAsync() { if (!Port.IsOpen) @@ -55,11 +52,7 @@ namespace NmeaParser return Task.FromResult(Port.BaseStream); } - /// - /// Closes the stream the NmeaDevice is working on top off. - /// - /// The stream. - /// + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { if (Port.IsOpen) diff --git a/src/NmeaParser/SerialPortDevice.UWP.cs b/src/NmeaParser/SerialPortDevice.UWP.cs index 9c572f5..5c5218f 100644 --- a/src/NmeaParser/SerialPortDevice.UWP.cs +++ b/src/NmeaParser/SerialPortDevice.UWP.cs @@ -54,20 +54,13 @@ namespace NmeaParser } } - /// - /// Creates the stream the NmeaDevice is working on top off. - /// - /// + /// protected override Task OpenStreamAsync() { return Task.FromResult(m_port.InputStream.AsStreamForRead(0)); } - /// - /// Closes the stream the NmeaDevice is working on top off. - /// - /// The stream. - /// + /// protected override Task CloseStreamAsync(System.IO.Stream stream) { return Task.CompletedTask; diff --git a/src/NmeaParser/StreamDevice.cs b/src/NmeaParser/StreamDevice.cs index e8cbafc..5188c20 100644 --- a/src/NmeaParser/StreamDevice.cs +++ b/src/NmeaParser/StreamDevice.cs @@ -36,20 +36,13 @@ namespace NmeaParser m_stream = stream ?? throw new ArgumentNullException(nameof(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