From 023d2a260ed43a5924cffd0e5d94924fa1de8bf8 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Tue, 15 Nov 2022 15:43:29 +0100 Subject: [PATCH 1/2] Update Essentials Barometer API Docs --- .../Microsoft.Maui.Essentials/Barometer.xml | 93 -------- .../BarometerChangedEventArgs.xml | 55 ----- .../BarometerData.xml | 199 ------------------ .../src/Barometer/Barometer.android.cs | 7 + .../src/Barometer/Barometer.shared.cs | 110 ++++++++-- 5 files changed, 103 insertions(+), 361 deletions(-) delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/Barometer.xml delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/BarometerChangedEventArgs.xml delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/BarometerData.xml diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/Barometer.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/Barometer.xml deleted file mode 100644 index 5db6a30ec470..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/Barometer.xml +++ /dev/null @@ -1,93 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Object - - - - Monitor changes to the atmospheric pressure. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - Gets if barometer is actively being monitored. - If barometer is being monitored. - - - - - - - - Event - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.EventHandler<Microsoft.Maui.Essentials.BarometerChangedEventArgs> - - - Event triggered when barometer reading changes. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Void - - - - - - The speed to listen for changes. - Start monitoring for changes to the barometer. - Will throw FeatureNotSupportedException if not supported on device. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Void - - - - Stop monitoring for changes to the barometer. - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/BarometerChangedEventArgs.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/BarometerChangedEventArgs.xml deleted file mode 100644 index f255ff163b7b..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/BarometerChangedEventArgs.xml +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.EventArgs - - - - The current pressure information from the change event. - - - - - - - - Constructor - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - - - The current reading - Public constructor for barometer changed event args. - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.BarometerData - - - Gets the current barometer pressure data - Pressure in hPA - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/BarometerData.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/BarometerData.xml deleted file mode 100644 index cbff201b0e34..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/BarometerData.xml +++ /dev/null @@ -1,199 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.ValueType - - - - System.IEquatable<Microsoft.Maui.Essentials.BarometerData> - - - - - System.Runtime.CompilerServices.IsReadOnly - - - - - Contains the pressure measured by the user's device. - - - - - - - - - Constructor - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - - - The current pressure - Public constructor for barometer data. - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - Object to compare - If equal to another object - If equal - - - - - - - - Method - - M:System.IEquatable`1.Equals(`0) - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - Other object to compare - If equal to another object - If equal - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Int32 - - - - Get has code for object. - The hash code. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - Left to compare - Right to compare - If equal to another object - If equal - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - Left to comapre - Right to comapre - If not equal to another object - If not equal - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - Gets the current pressure in hectopascals. - - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.String - - - - Outputs the data as a string. - - To be added. - - - - diff --git a/src/Essentials/src/Barometer/Barometer.android.cs b/src/Essentials/src/Barometer/Barometer.android.cs index b8c6125603c8..e606814c056a 100644 --- a/src/Essentials/src/Barometer/Barometer.android.cs +++ b/src/Essentials/src/Barometer/Barometer.android.cs @@ -37,11 +37,18 @@ void PlatformStop() class BarometerListener : Java.Lang.Object, ISensorEventListener, IDisposable { + /// + /// Initializes a new instance of the class. + /// + /// The handler that is invoked when a change in the barometer reading is detected. public BarometerListener(Action changeHandler) { ChangeHandler = changeHandler; } + /// + /// A reference to the action that invoked when a change in the barometer reading has been detected. + /// public readonly Action ChangeHandler; void ISensorEventListener.OnAccuracyChanged(Sensor? sensor, SensorStatus accuracy) diff --git a/src/Essentials/src/Barometer/Barometer.shared.cs b/src/Essentials/src/Barometer/Barometer.shared.cs index c7a0820d550d..ff2ca10d756b 100644 --- a/src/Essentials/src/Barometer/Barometer.shared.cs +++ b/src/Essentials/src/Barometer/Barometer.shared.cs @@ -4,44 +4,85 @@ namespace Microsoft.Maui.Devices.Sensors { + /// + /// Monitor changes to the atmospheric pressure. + /// public interface IBarometer { + /// + /// Gets if reading the barometer is supported on this device. + /// bool IsSupported { get; } + /// + /// Gets if the barometer is actively being monitored. + /// bool IsMonitoring { get; } + /// + /// Start monitoring for changes to the barometer. + /// + /// The speed to listen for changes. void Start(SensorSpeed sensorSpeed); + /// + /// Event triggered when barometer reading changes. + /// event EventHandler? ReadingChanged; + /// + /// Stop monitoring for changes to the barometer. + /// void Stop(); } - /// + /// + /// Monitor changes to the atmospheric pressure. + /// public static class Barometer { + /// + /// Event triggered when barometer reading changes. + /// public static event EventHandler ReadingChanged { add => Default.ReadingChanged += value; remove => Default.ReadingChanged -= value; } + /// + /// Gets if reading the accelerometer is supported on this device. + /// public static bool IsSupported => Default.IsSupported; - /// + /// + /// Gets if the barometer is actively being monitored. + /// public static bool IsMonitoring => Default.IsMonitoring; - /// + /// + /// Start monitoring for changes to the barometer. + /// + /// + /// Will throw if not supported on device. + /// Will throw if is . + /// + /// The speed to listen for changes. public static void Start(SensorSpeed sensorSpeed) => Default.Start(sensorSpeed); - /// + /// + /// Stop monitoring for changes to the barometer. + /// public static void Stop() => Default.Stop(); static IBarometer? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IBarometer Default => defaultImplementation ??= new BarometerImplementation(); @@ -49,46 +90,82 @@ internal static void SetDefault(IBarometer? implementation) => defaultImplementation = implementation; } - /// + /// + /// Contains the current pressure information from the event. + /// public class BarometerChangedEventArgs : EventArgs { - /// + /// + /// Initializes a new instance of the class. + /// + /// The barometer data reading. public BarometerChangedEventArgs(BarometerData reading) => Reading = reading; - /// + /// + /// The current values of the barometer. + /// public BarometerData Reading { get; } } - /// + /// + /// Contains the pressure measured by the user's device barometer. + /// public readonly struct BarometerData : IEquatable { - /// + /// + /// Initializes a new instance of the class. + /// + /// The current pressure reading. public BarometerData(double pressure) => PressureInHectopascals = pressure; - /// + /// + /// Gets the current pressure in hectopascals. + /// public double PressureInHectopascals { get; } + /// + /// Equality operator for equals. + /// + /// Left to compare. + /// Left to compare. + /// if objects are equal, otherwise . public static bool operator ==(BarometerData left, BarometerData right) => left.Equals(right); + /// + /// Inequality operator. + /// + /// Left to compare. + /// Left to compare. + /// if objects are not equal, otherwise . public static bool operator !=(BarometerData left, BarometerData right) => !left.Equals(right); - /// + /// + /// Compares the underlying instances. + /// + /// Object to compare with. + /// if they are equal, otherwise . public override bool Equals(object? obj) => (obj is BarometerData data) && Equals(data); - /// + /// + /// Compares the underlying instances. + /// + /// object to compare with. + /// if they are equal, otherwise . public bool Equals(BarometerData other) => PressureInHectopascals.Equals(other.PressureInHectopascals); - /// public override int GetHashCode() => PressureInHectopascals.GetHashCode(); - /// + /// + /// Returns a string representation of the current values of . + /// + /// A string representation of this instance in the format of PressureInHectopascals: {value}. public override string ToString() => $"{nameof(PressureInHectopascals)}: {PressureInHectopascals}"; } @@ -114,6 +191,9 @@ void RaiseReadingChanged(BarometerData reading) ReadingChanged?.Invoke(this, args); } + /// + /// Thrown if returns . + /// Thrown if returns . public void Start(SensorSpeed sensorSpeed) { if (!IsSupported) @@ -136,6 +216,8 @@ public void Start(SensorSpeed sensorSpeed) } } + /// + /// Thrown if returns . public void Stop() { if (!IsSupported) From b904c2cf265f99180c6fd7f259a7b47cf0f44b22 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Tue, 15 Nov 2022 21:09:00 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: E.Z. Hart --- src/Essentials/src/Barometer/Barometer.shared.cs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/Essentials/src/Barometer/Barometer.shared.cs b/src/Essentials/src/Barometer/Barometer.shared.cs index ff2ca10d756b..2fe5818b0ab9 100644 --- a/src/Essentials/src/Barometer/Barometer.shared.cs +++ b/src/Essentials/src/Barometer/Barometer.shared.cs @@ -10,12 +10,12 @@ namespace Microsoft.Maui.Devices.Sensors public interface IBarometer { /// - /// Gets if reading the barometer is supported on this device. + /// Gets a value indicating whether reading the barometer is supported on this device. /// bool IsSupported { get; } /// - /// Gets if the barometer is actively being monitored. + /// Gets a value indicating whether the barometer is actively being monitored. /// bool IsMonitoring { get; } @@ -26,7 +26,7 @@ public interface IBarometer void Start(SensorSpeed sensorSpeed); /// - /// Event triggered when barometer reading changes. + /// Occurs when the barometer reading changes. /// event EventHandler? ReadingChanged; @@ -42,7 +42,7 @@ public interface IBarometer public static class Barometer { /// - /// Event triggered when barometer reading changes. + /// Occurs when barometer reading changes. /// public static event EventHandler ReadingChanged { @@ -51,12 +51,12 @@ public static event EventHandler ReadingChanged } /// - /// Gets if reading the accelerometer is supported on this device. + /// Gets a value indicating whether reading the accelerometer is supported on this device. /// public static bool IsSupported => Default.IsSupported; /// - /// Gets if the barometer is actively being monitored. + /// Gets a value indicating whether the barometer is actively being monitored. /// public static bool IsMonitoring => Default.IsMonitoring;