Документация проекта отображения.

Pf2eViewer/DatabaseViewer/DatabaseViewerControl.cs

@@ -8,10 +8,21 @@ using Timer = System.Windows.Forms.Timer;
 
 namespace Pf2eViewer.DatabaseViewer;
 
+/// <summary>
+/// Класс элемента управления, который отображает сущности в виде таблицы.
+/// </summary>
 public partial class DatabaseViewerControl : UserControl
 {
+    #region "Поля и свойства"
+
+    /// <summary>
+    /// Контекст базы данных, который используется для получения сущностей.
+    /// </summary>
     public readonly Pf2eDbContext Context = new();
 
+    /// <summary>
+    /// Количество элементов на странице.
+    /// </summary>
     [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
     public int PerPage
     {
@@ -24,6 +35,9 @@ public partial class DatabaseViewerControl : UserControl
     }
     private int _perPage = 30;
 
+    /// <summary>
+    /// Номер страницы, которую необходимо отобразить.
+    /// </summary>
     [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
     public int Page
     {
@@ -36,6 +50,9 @@ public partial class DatabaseViewerControl : UserControl
     }
     private int _page = 1;
 
+    /// <summary>
+    /// Тип сущности, которую необходимо отобразить.
+    /// </summary>
     [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
     public EntityType Type
     {
@@ -49,23 +66,49 @@ public partial class DatabaseViewerControl : UserControl
     }
     private EntityType _type;
 
+    /// <summary>
+    /// Количество элементов, которые были получены из базы данных.
+    /// </summary>
     [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
     public int Count { get; private set; }
 
+    /// <summary>
+    /// Номер последней страницы, которая может быть отображена.
+    /// </summary>
     public int MaxPage => Convert.ToInt32(Math.Ceiling(1.0 * Count / PerPage));
 
+    /// <summary>
+    /// Выбранная в элементе управления сущность.
+    /// </summary>
     [AllowNull]
     [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
     public EntityView CurrentEntity { get; private set; }
 
+    /// <summary>
+    /// Флаг, указывающий, что элемент управления занят выполнением запроса к базе данных.
+    /// </summary>
     private bool _isBusy = true;
 
+    /// <summary>
+    /// Объект, который выполняет запрос к базе данных.
+    /// </summary>
     private DatabaseQueryPerformer? _performer;
 
+    /// <summary>
+    /// Таймер, который используется для задержки обработки события изменения текста в поле поиска.
+    /// </summary>
     private Timer? _typingTimer;
 
+    /// <summary>
+    /// Строка, которая хранит последнее значение, введенное в поле поиска.
+    /// </summary>
     private string _lastSearch = "";
 
+    #endregion
+
+    /// <summary>
+    /// Конструктор класса, который инициализирует элемент управления и связывает его с источником данных.
+    /// </summary>
     public DatabaseViewerControl()
     {
         InitializeComponent();
@@ -77,8 +120,13 @@ public partial class DatabaseViewerControl : UserControl
         _isBusy = false;
     }
 
-    // Control events
+    #region "События элемента управления"
 
+    /// <summary>
+    /// Обработчик события, который вызывается при изменении текущей страницы в элементе управления.
+    /// </summary>
+    /// <param name="sender">Источник события.</param>
+    /// <param name="e">Объект, содержащий данные события.</param>
     private void BindingNavigator_RefreshItems(object sender, EventArgs e)
     {
         if (_isBusy)
@@ -90,6 +138,11 @@ public partial class DatabaseViewerControl : UserControl
         UpdateView();
     }
 
+    /// <summary>
+    /// Обработчик события, который вызывается при изменении выделенной строки в элементе управления DataGridView.
+    /// </summary>
+    /// <param name="sender">Источник события.</param>
+    /// <param name="e">Объект, содержащий данные события.</param>
     private void DataGridView_RowStateChanged(object sender, DataGridViewRowStateChangedEventArgs e)
     {
         if (_isBusy)
@@ -100,6 +153,11 @@ public partial class DatabaseViewerControl : UserControl
         UpdateEntity();
     }
 
+    /// <summary>
+    /// Обработчик события, который вызывается когда поле поиска теряет фокус.
+    /// </summary>
+    /// <param name="sender">Источник события.</param>
+    /// <param name="e">Объект, содержащий данные события.</param>
     private void SearchTextBox_Leave(object sender, EventArgs e)
     {
         if (_isBusy || SearchTextBox.Text == _lastSearch)
@@ -110,6 +168,11 @@ public partial class DatabaseViewerControl : UserControl
         UpdateView();
     }
 
+    /// <summary>
+    /// Обработчик события, который вызывается при изменении текста в поле поиска.
+    /// </summary>
+    /// <param name="sender">Источник события.</param>
+    /// <param name="e">Объект, содержащий данные события.</param>
     private void SearchTextBox_TextChanged(object sender, EventArgs e)
     {
         if (_isBusy)
@@ -128,6 +191,11 @@ public partial class DatabaseViewerControl : UserControl
         _typingTimer.Start();
     }
 
+    /// <summary>
+    /// Обработчик события, который вызывается при истечении времени таймера ввода текста.
+    /// </summary>
+    /// <param name="sender">Источник события.</param>
+    /// <param name="e">Объект, содержащий данные события.</param>
     private void HandleTypingTimerTimeout(object? sender, EventArgs e)
     {
         if (_isBusy || sender is not Timer timer)
@@ -139,8 +207,14 @@ public partial class DatabaseViewerControl : UserControl
         timer.Stop();
     }
 
-    // Updater
+    #endregion
 
+    #region "Обновление данных"
+
+    /// <summary>
+    /// Устанавливает статус занятости элемента управления.
+    /// </summary>
+    /// <param name="busy">Новый статус занятости.</param>
     private void SetBusyStatus(bool busy)
     {
         if (InvokeRequired)
@@ -160,6 +234,10 @@ public partial class DatabaseViewerControl : UserControl
             : DataGridViewColumnHeadersHeightSizeMode.DisableResizing;
     }
 
+    /// <summary>
+    /// Обновляет данные в элементе управления.
+    /// </summary>
+    /// <param name="force">Проигнорировать флаг занятости.</param>
     public void UpdateView(bool force = false)
     {
         if (_isBusy && !force)
@@ -184,6 +262,11 @@ public partial class DatabaseViewerControl : UserControl
         _performer.Query();
     }
 
+    /// <summary>
+    /// Обработчик события, который вызывается по завершении выполнения запроса к базе данных.
+    /// </summary>
+    /// <param name="sender">Источник события.</param>
+    /// <param name="result">Результат выполнения события</param>
     private void HandleQueryCompleted(DatabaseQueryPerformer sender, DatabaseQueryResult result)
     {
         if (sender != _performer)
@@ -223,6 +306,12 @@ public partial class DatabaseViewerControl : UserControl
         );
     }
 
+    /// <summary>
+    /// Вызывает действие на указанном элементе управления в нужном потоке , если это необходимо.
+    /// </summary>
+    /// <typeparam name="T"></typeparam>
+    /// <param name="control"></param>
+    /// <param name="action"></param>
     private void InvokeControl<T>(T control, Action<T> action)
         where T : Control
     {
@@ -236,6 +325,9 @@ public partial class DatabaseViewerControl : UserControl
         }
     }
 
+    /// <summary>
+    /// Обновить сущность, которая была выбрана в элементе управления DataGridView.
+    /// </summary>
     private void UpdateEntity()
     {
         if (DataGridView.SelectedRows.Count == 0)
@@ -257,18 +349,42 @@ public partial class DatabaseViewerControl : UserControl
         EntityChange?.Invoke(CurrentEntity);
     }
 
-    // Output events
+    #endregion
 
+    #region Output events
+
+    /// <summary>
+    /// Делегат, который будет вызван при изменении выбранной сущности.
+    /// </summary>
+    /// <param name="newEntity">Новая выбранная сущность.</param>
     public delegate void EntityChangeHandler(EntityView newEntity);
 
+    /// <summary>
+    /// Событие, которое вызывается при изменении выбранной сущности.
+    /// </summary>
     public event EntityChangeHandler? EntityChange;
 
-    internal class EntityGridRow(Entity e)
+    #endregion
+
+    /// <summary>
+    /// Класс, который представляет строку в таблице сущностей.
+    /// </summary>
+    /// <param name="entity">Сущность, связанная со строкой</param>
+    internal class EntityGridRow(Entity entity)
     {
-        public int Id { get; set; } = e.Id;
+        /// <summary>
+        /// Идентификатор сущности.
+        /// </summary>
+        public int Id { get; set; } = entity.Id;
 
-        public string Name { get; set; } = e.Name[LocaleType.English];
+        /// <summary>
+        /// Название сущности.
+        /// </summary>
+        public string Name { get; set; } = entity.Name[LocaleType.English];
 
-        public EntityRarity Rarity { get; set; } = e.Rarity;
+        /// <summary>
+        /// Редкость сущности.
+        /// </summary>
+        public EntityRarity Rarity { get; set; } = entity.Rarity;
     }
 }