20250810-1 v1.0

help/class_desc/attributes/Compare.md

@@ -10,25 +10,48 @@
 Например, это может понадобиться, если простое сравнение двух значений недостаточно точно отражает вашу бизнес-логику (
 например, если нужно сравнивать значения с учётом округления или игнорируя регистр букв).
 
+## Синтаксис использования
+
+Атрибут принимает один обязательный параметр типа `string|array|null`, который определяет способ сравнения. Возможны
+следующие варианты:
+
+* Строка — имя статического метода.
+* Массив — [класс, метод].
+* null — сравнение по умолчанию.
+
 ## Пример использования атрибута
 
-Допустим, у вас есть модель данных, включающая поле, содержащее имя пользователя, и вы хотите сравнить имена независимо
-от регистра:
+### Пример 1: Использование статического метода
 
 ```php
 use goodboyalex\php_db_components_pack\attributes\Compare;
 
 final class User
 {
-    #[Compare(fn($left, $right) => strcasecmp($left, $right))]
-    private string $Name;
-
-    // Остальные поля и геттеры/сеттеры...
+    #[Compare('App\Comparators\StringComparator::caseInsensitiveCompare')]
+    public string $Name;
 }
 ```
 
-В данном примере атрибут `#[Compare]` применяется к полю `$Name`, и указанное замыкание (closure) реализует
-сравнение строк без учёта регистра.
+#### Пример 2: Использование массива для вызова метода
+
+```php
+final class Measurement
+{
+    #[Compare('App\Comparators\NumberComparator', 'compareWithTolerance')]
+    public float $Value;
+}
+```
+
+#### Пример 3: Сравнение по умолчанию
+
+```php
+final class Event
+{
+    #[Compare(null)]
+    public string $Date;
+}
+```
 
 ## Пространство имён
 
@@ -49,6 +72,13 @@ namespace goodboyalex\php_db_components_pack\attributes;
 - **Применяется только к полям (properties)**  
   Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
 
+## Важные замечания
+
+* Все указанные методы должны быть статическими.
+* При некорректном определении компаратора будет выброшено исключение.
+* Рекомендуется создавать отдельные классы компараторов для лучшей поддерживаемости кода.
+* Методы сравнения должны корректно обрабатывать все возможные значения поля.
+
 ## Когда использовать атрибут?
 
 Атрибут `Compare` идеально подойдёт, когда вам необходимо установить особое правило сравнения значений. Например, если