Merge pull request #88 from w-ahmad/comments

added comments on types and members

Author: w-ahmad

src/WinUI.TableView/Controls/TableViewDatePicker.cs

@@ -5,15 +5,24 @@
 
 namespace WinUI.TableView.Controls;
 
+/// <summary>
+/// Represents a date editing element for the TableViewDateColumn.
+/// </summary>
 public partial class TableViewDatePicker : CalendarDatePicker
 {
     private bool _deferUpdate;
 
+    /// <summary>
+    /// Initializes a new instance of the TableViewDatePicker class.
+    /// </summary>
     public TableViewDatePicker()
     {
         DateChanged += OnDateChanged;
     }
 
+    /// <summary>
+    /// Handles the DateChanged event.
+    /// </summary>
     private void OnDateChanged(CalendarDatePicker sender, CalendarDatePickerDateChangedEventArgs args)
     {
         if (_deferUpdate) return;
@@ -46,6 +55,9 @@ private void OnDateChanged(CalendarDatePicker sender, CalendarDatePickerDateChan
         _deferUpdate = false;
     }
 
+    /// <summary>
+    /// Handles changes to the SelectedDate property.
+    /// </summary>
     private static void OnSelectedDateChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
     {
         if (d is TableViewDatePicker datePicker && !datePicker._deferUpdate)
@@ -63,13 +75,23 @@ private static void OnSelectedDateChanged(DependencyObject d, DependencyProperty
         }
     }
 
+    /// <summary>
+    /// Gets or sets the source type of the date picker.
+    /// This value could be DateOnly, DateTime, or DateTimeOffset.
+    /// </summary>
     internal Type? SourceType { get; set; }
 
+    /// <summary>
+    /// Gets or sets the selected date.
+    /// </summary>
     public object? SelectedDate
     {
         get => GetValue(SelectedDateProperty);
         set => SetValue(SelectedDateProperty, value);
     }
 
+    /// <summary>
+    /// Identifies the SelectedDate dependency property.
+    /// </summary>
     public static readonly DependencyProperty SelectedDateProperty = DependencyProperty.Register(nameof(SelectedDate), typeof(object), typeof(TableViewDatePicker), new PropertyMetadata(default, OnSelectedDateChanged));
 }

src/WinUI.TableView/Controls/TableViewTimePicker.cs

@@ -9,11 +9,17 @@
 
 namespace WinUI.TableView.Controls;
 
+/// <summary>
+/// Represents a time editing element for the TableViewTimeColumn.
+/// </summary>
 public class TableViewTimePicker : Control
 {
     private TextBlock? _timeText;
     private readonly TimePickerFlyout _flyout;
 
+    /// <summary>
+    /// Initializes a new instance of the TableViewTimePicker class.
+    /// </summary>
     public TableViewTimePicker()
     {
         DefaultStyleKey = typeof(TableViewTimePicker);
@@ -50,6 +56,9 @@ protected override void OnKeyDown(KeyRoutedEventArgs e)
         }
     }
 
+    /// <summary>
+    /// Shows the time picker flyout.
+    /// </summary>
     private void ShowFlyout()
     {
         _flyout.Time = SelectedTime switch
@@ -66,6 +75,9 @@ private void ShowFlyout()
         _flyout.ShowAt(this);
     }
 
+    /// <summary>
+    /// Handles the TimePicked event of the flyout.
+    /// </summary>
     private void OnTimePicked(TimePickerFlyout sender, TimePickedEventArgs args)
     {
         var oldTime = SelectedTime is null ? TimeSpan.Zero : args.OldTime;
@@ -91,6 +103,9 @@ private void OnTimePicked(TimePickerFlyout sender, TimePickedEventArgs args)
         }
     }
 
+    /// <summary>
+    /// Updates the text displayed in the time picker.
+    /// </summary>
     private void UpdateTimeText()
     {
         if (_timeText is null) return;
@@ -108,6 +123,9 @@ private void UpdateTimeText()
         };
     }
 
+    /// <summary>
+    /// Handles changes to the SelectedTime property.
+    /// </summary>
     private static void OnSelectedTimeChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
     {
         if (d is TableViewTimePicker timePicker)
@@ -117,6 +135,9 @@ private static void OnSelectedTimeChanged(DependencyObject d, DependencyProperty
         }
     }
 
+    /// <summary>
+    /// Handles changes to the PlaceholderText property.
+    /// </summary>
     private static void OnPlaceHolderTextChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
     {
         if (d is TableViewTimePicker timePicker)
@@ -125,6 +146,9 @@ private static void OnPlaceHolderTextChanged(DependencyObject d, DependencyPrope
         }
     }
 
+    /// <summary>
+    /// Handles changes to the ClockIdentifier property.
+    /// </summary>
     private static void OnClockIdentifierChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
     {
         if (d is TableViewTimePicker timePicker)
@@ -133,34 +157,65 @@ private static void OnClockIdentifierChanged(DependencyObject d, DependencyPrope
         }
     }
 
+    /// <summary>
+    /// Gets or sets the source type of the time picker.
+    /// The value could be TimeSpan, TimeOnly, DateTime, or DateTimeOffset.
+    /// </summary>
     internal Type? SourceType { get; set; }
 
+    /// <summary>
+    /// Gets or sets the selected time.
+    /// </summary>
     public object? SelectedTime
     {
         get => GetValue(SelectedTimeProperty);
         set => SetValue(SelectedTimeProperty, value);
     }
 
+    /// <summary>
+    /// Gets or sets the placeholder text for the time picker.
+    /// </summary>
     public string? PlaceholderText
     {
         get => (string?)GetValue(PlaceholderTextProperty);
         set => SetValue(PlaceholderTextProperty, value);
     }
 
+    /// <summary>
+    /// Gets or sets the clock identifier for the time picker.
+    /// </summary>
     public string ClockIdentifier
     {
         get => (string)GetValue(ClockIdentifierProperty);
         set => SetValue(ClockIdentifierProperty, value);
     }
 
+    /// <summary>
+    /// Gets or sets the minute increment for the time picker.
+    /// </summary>
     public int MinuteIncrement
     {
         get => (int)GetValue(MinuteIncrementProperty);
         set => SetValue(MinuteIncrementProperty, value);
     }
 
+    /// <summary>
+    /// Identifies the MinuteIncrement dependency property.
+    /// </summary>
     public static readonly DependencyProperty MinuteIncrementProperty = DependencyProperty.Register(nameof(MinuteIncrement), typeof(int), typeof(TableViewTimePicker), new PropertyMetadata(1));
+
+    /// <summary>
+    /// Identifies the SelectedTime dependency property.
+    /// </summary>
     public static readonly DependencyProperty SelectedTimeProperty = DependencyProperty.Register(nameof(SelectedTime), typeof(object), typeof(TableViewTimePicker), new PropertyMetadata(default, OnSelectedTimeChanged));
+
+    /// <summary>
+    /// Identifies the PlaceholderText dependency property.
+    /// </summary>
     public static readonly DependencyProperty PlaceholderTextProperty = DependencyProperty.Register(nameof(PlaceholderText), typeof(string), typeof(TableViewTimePicker), new PropertyMetadata("pick a time", OnPlaceHolderTextChanged));
+
+    /// <summary>
+    /// Identifies the ClockIdentifier dependency property.
+    /// </summary>
     public static readonly DependencyProperty ClockIdentifierProperty = DependencyProperty.Register(nameof(ClockIdentifier), typeof(string), typeof(TableViewTimePicker), new PropertyMetadata(default, OnClockIdentifierChanged));
 }

src/WinUI.TableView/Extensions/DateTimeExtensions.cs

@@ -2,23 +2,46 @@
 
 namespace WinUI.TableView.Extensions;
 
+/// <summary>
+/// Provides extension methods for Date&Time types.
+/// </summary>
 internal static class DateTimeExtensions
 {
+    /// <summary>
+    /// Converts a DateTime to a DateTimeOffset using the local time zone.
+    /// </summary>
+    /// <param name="dateTime">The DateTime to convert.</param>
+    /// <returns>A DateTimeOffset representing the same point in time as the DateTime.</returns>
     public static DateTimeOffset ToDateTimeOffset(this DateTime dateTime)
     {
         return new DateTimeOffset(dateTime, TimeZoneInfo.Local.GetUtcOffset(dateTime));
     }
 
+    /// <summary>
+    /// Converts a TimeSpan to a DateTimeOffset using the current date.
+    /// </summary>
+    /// <param name="timeSpan">The TimeSpan to convert.</param>
+    /// <returns>A DateTimeOffset representing the same time of day as the TimeSpan on the current date.</returns>
     public static DateTimeOffset ToDateTimeOffset(this TimeSpan timeSpan)
     {
         return DateTime.Today.Add(timeSpan).ToDateTimeOffset();
     }
 
+    /// <summary>
+    /// Converts a DateOnly to a DateTimeOffset using the minimum time of day.
+    /// </summary>
+    /// <param name="dateOnly">The DateOnly to convert.</param>
+    /// <returns>A DateTimeOffset representing the same date as the DateOnly with the minimum time of day.</returns>
     public static DateTimeOffset ToDateTimeOffset(this DateOnly dateOnly)
     {
         return dateOnly.ToDateTime(TimeOnly.MinValue).ToDateTimeOffset();
     }
 
+    /// <summary>
+    /// Converts a TimeOnly to a DateTimeOffset using the current date.
+    /// </summary>
+    /// <param name="timeOnly">The TimeOnly to convert.</param>
+    /// <returns>A DateTimeOffset representing the same time of day as the TimeOnly on the current date.</returns>
     public static DateTimeOffset ToDateTimeOffset(this TimeOnly timeOnly)
     {
         return timeOnly.ToTimeSpan().ToDateTimeOffset();

src/WinUI.TableView/Extensions/ItemIndexRangeExtensions.cs

@@ -2,10 +2,19 @@
 
 namespace WinUI.TableView.Extensions;
 
+/// <summary>
+/// Provides extension methods for the ItemIndexRange type.
+/// </summary>
 public static class ItemIndexRangeExtensions
 {
+    /// <summary>
+    /// Determines whether a specified index is within the range.
+    /// </summary>
+    /// <param name="range">The ItemIndexRange to check.</param>
+    /// <param name="index">The index to check.</param>
+    /// <returns>True if the index is within the range; otherwise, false.</returns>
     public static bool IsInRange(this ItemIndexRange range, int index)
     {
         return index >= range.FirstIndex && index <= range.LastIndex;
     }
-}
+}

src/WinUI.TableView/Extensions/ObjectExtensions.cs

@@ -3,8 +3,17 @@
 
 namespace WinUI.TableView.Extensions;
 
+/// <summary>
+/// Provides extension methods for object types.
+/// </summary>
 internal static class ObjectExtensions
 {
+    /// <summary>
+    /// Gets the value of a property from an object using a sequence of property info and index pairs.
+    /// </summary>
+    /// <param name="obj">The object from which to get the value.</param>
+    /// <param name="pis">An array of property info and index pairs.</param>
+    /// <returns>The value of the property, or null if the object is null.</returns>
     internal static object? GetValue(this object? obj, (PropertyInfo pi, object? index)[] pis)
     {
         foreach (var pi in pis)
@@ -20,6 +29,14 @@ internal static class ObjectExtensions
         return obj;
     }
 
+    /// <summary>
+    /// Gets the value of a property from an object using a type and a property path.
+    /// </summary>
+    /// <param name="obj">The object from which to get the value.</param>
+    /// <param name="type">The type of the object.</param>
+    /// <param name="path">The property path.</param>
+    /// <param name="pis">An array of property info and index pairs.</param>
+    /// <returns>The value of the property, or null if the object is null.</returns>
     internal static object? GetValue(this object? obj, Type? type, string path, out (PropertyInfo pi, object? index)[] pis)
     {
         var parts = path.Split('.');

src/WinUI.TableView/Extensions/TableViewCellSlotExtensions.cs

@@ -1,17 +1,38 @@
 namespace WinUI.TableView.Extensions;
 
+/// <summary>
+/// Provides extension methods for the TableViewCellSlot type.
+/// </summary>
 internal static class TableViewCellSlotExtensions
 {
+    /// <summary>
+    /// Determines whether the row index of the slot is valid within the TableView.
+    /// </summary>
+    /// <param name="slot">The TableViewCellSlot to check.</param>
+    /// <param name="tableView">The TableView to check against.</param>
+    /// <returns>True if the row index of TableView is valid; otherwise, false.</returns>
     public static bool IsValidRow(this TableViewCellSlot slot, TableView tableView)
     {
         return slot.Row >= 0 && slot.Row < tableView?.Items.Count;
     }
 
+    /// <summary>
+    /// Determines whether the column index of the slot is valid within the TableView.
+    /// </summary>
+    /// <param name="slot">The TableViewCellSlot to check.</param>
+    /// <param name="tableView">The TableView to check against.</param>
+    /// <returns>True if the column index TableView is valid; otherwise, false.</returns>
     public static bool IsValidColumn(this TableViewCellSlot slot, TableView tableView)
     {
         return slot.Column >= 0 && slot.Column < tableView?.Columns.VisibleColumns.Count;
     }
 
+    /// <summary>
+    /// Determines whether both the row and column indices of the slot are valid within the TableView.
+    /// </summary>
+    /// <param name="slot">The TableViewCellSlot to check.</param>
+    /// <param name="tableView">The TableView to check against.</param>
+    /// <returns>True if both the row and column indices of TableView are valid; otherwise, false.</returns>
     public static bool IsValid(this TableViewCellSlot slot, TableView tableView)
     {
         return slot.IsValidRow(tableView) && slot.IsValidColumn(tableView);