Update doc for insert, update and save methods

src/ActiveRecordInterface.php

@@ -174,7 +174,7 @@ public function primaryKeyOldValue(): float|int|string|null;
     /**
      * Returns the old values of the primary key as an array with property names as keys and property values as values.
      *
-     * This refers to the primary key values that is populated into the record after data is retrieved from the database
+     * This refers to the primary key values that are populated into the record after data is retrieved from the database
      * by an instance of {@see ActiveQueryInterface}.
      *
      * The value remains unchanged while the record will not be {@see ActiveRecordInterface::update() updated}.
@@ -342,11 +342,9 @@ public function hasMany(self|string $modelClass, array $link): ActiveQueryInterf
     public function hasOne(self|string $modelClass, array $link): ActiveQueryInterface;
 
     /**
-     * Inserts a row into the associated database table using the property values of this record.
-     * You may specify the properties to be inserted as list of name or name-value pairs.
-     * If name-value pair specified, the corresponding property values will be modified.
+     * Inserts a new row into the associated database table using the property values of this record.
      *
-     * Only the {@see ActiveRecordInterface::newValues()} changed property values will be inserted into a database.
+     * Only the {@see ActiveRecordInterface::newValues()} changed property values will be inserted into the database.
      *
      * If the table's primary key is auto incremental and is `null` during insertion, it will be populated with the
      * actual value after insertion.
@@ -366,8 +364,9 @@ public function hasOne(self|string $modelClass, array $link): ActiveQueryInterfa
      * $customer->insert(['name' => $name, 'email' => $email]);
      * ```
      *
-     * @param array|null $properties List of property names or name-values pairs that need to be saved.
-     * Defaults to `null`, meaning all changed property values will be saved.
+     * @param array|null $properties List of property names or name-values pairs that need to be inserted.
+     * If name-value pairs are specified, the corresponding property values will be modified before insertion.
+     * Defaults to `null`, meaning all changed property values will be inserted.
      *
      * @throws InvalidCallException If the record {@see ActiveRecordInterface::isNew() is not new}.
      * @throws InvalidConfigException
@@ -526,10 +525,8 @@ public function resetRelation(string $name): void;
 
     /**
      * Saves the changes to this active record into the associated database table.
-     * You may specify the properties to be updated as list of name or name-value pairs.
-     * If name-value pair specified, the corresponding property values will be modified.
      *
-     * Only the {@see ActiveRecordInterface::newValues()} changed property values will be saved into a database.
+     * Only the {@see ActiveRecordInterface::newValues()} changed property values will be saved into the database.
      *
      * This method will call {@see ActiveRecordInterface::insert()} when {@see ActiveRecordInterface::isNew()}
      * is true, or {@see ActiveRecordInterface::update()} when {@see ActiveRecordInterface::isNew()} is false.
@@ -550,6 +547,7 @@ public function resetRelation(string $name): void;
      * ```
      *
      * @param array|null $properties List of property names or name-values pairs that need to be saved.
+     * If name-value pairs are specified, the corresponding property values will be modified before saving.
      * Defaults to `null`, meaning all changed property values will be saved.
      */
     public function save(?array $properties = null): void;
@@ -582,13 +580,9 @@ public function markAsNew(): void;
     public function markAsExisting(): void;
 
     /**
-     * Saves the changes to this active record into the associated database table.
-     * You may specify the properties to be updated as list of name or name-value pairs.
-     * If name-value pair specified, the corresponding property values will be modified.
+     * Updates the changes to this active record into the associated database table.
      *
-     * The method will then save the specified properties into a database.
-     *
-     * Only the {@see ActiveRecordInterface::newValues()} changed property values will be saved into a database.
+     * Only the {@see ActiveRecordInterface::newValues()} changed property values will be updated into the database.
      *
      * For example, to update a customer record:
      *
@@ -617,8 +611,9 @@ public function markAsExisting(): void;
      * }
      * ```
      *
-     * @param array|null $properties List of property names or name-values pairs that need to be saved.
-     * Defaults to `null`, meaning all changed property values will be saved.
+     * @param array|null $properties List of property names or name-values pairs that need to be updated.
+     * If name-value pairs are specified, the corresponding property values will be modified before updating.
+     * Defaults to `null`, meaning all changed property values will be updated.
      *
      * @throws InvalidCallException If the record {@see ActiveRecordInterface::isNew() is new}.
      * @throws OptimisticLockException If the instance implements {@see OptimisticLockInterface} and the data being

src/Event/BeforeInsert.php

@@ -8,15 +8,17 @@
 
 /**
  * Event triggered before a new record is inserted into the database.
- * It allows to modify properties that will be used for {@see ActiveRecordInterface::insert()} operation.
+ * It allows modifying properties that will be used for {@see ActiveRecordInterface::insert()} operation.
  *
  * @see ActiveRecordInterface::insert()
  */
 final class BeforeInsert extends AbstractEvent
 {
     /**
      * @param ActiveRecordInterface $model The model that is being inserted.
-     * @param array|null &$properties The properties that will be used for the insert operation.
+     * @param array|null &$properties List of property names or name-values pairs that need to be inserted.
+     * If name-value pairs are specified, the values will be used for insertion.
+     * If `null`, the properties will be taken from the model.
      */
     public function __construct(ActiveRecordInterface $model, public ?array &$properties)
     {

src/Event/BeforePopulate.php

@@ -8,15 +8,15 @@
 
 /**
  * Event triggered before the model is populated with data.
- * It allows to modify the data that will be used for {@see ActiveRecordInterface::populateRecord()} operation.
+ * It allows modifying the data that will be used for {@see ActiveRecordInterface::populateRecord()} operation.
  *
  * @see ActiveRecordInterface::populateRecord()
  */
 final class BeforePopulate extends AbstractEvent
 {
     /**
      * @param ActiveRecordInterface $model The model that will be populated.
-     * @param array &$data The data that will be used to populate the model.
+     * @param array &$data Property values (name => value) to be assigned to the model.
      */
     public function __construct(ActiveRecordInterface $model, public array &$data)
     {

src/Event/BeforeSave.php

@@ -8,15 +8,17 @@
 
 /**
  * Event triggered before the model is saved (inserted or updated) to the database.
- * It allows to modify properties that will be used for {@see ActiveRecordInterface::save()} operation.
+ * It allows modifying properties that will be used for {@see ActiveRecordInterface::save()} operation.
  *
  * @see ActiveRecordInterface::save()
  */
 final class BeforeSave extends AbstractEvent
 {
     /**
      * @param ActiveRecordInterface $model The model that is being saved.
-     * @param array|null &$properties The properties that will be used for the save operation.
+     * @param array|null &$properties List of property names or name-values pairs that need to be saved.
+     * If name-value pairs are specified, the values will be used for saving.
+     * If `null`, the properties will be taken from the model.
      */
     public function __construct(ActiveRecordInterface $model, public ?array &$properties)
     {

src/Event/BeforeUpdate.php

@@ -8,15 +8,17 @@
 
 /**
  * Event triggered before the record is updated in the database.
- * It allows to modify properties that will be used for {@see ActiveRecordInterface::update()} operation.
+ * It allows modifying properties that will be used for {@see ActiveRecordInterface::update()} operation.
  *
  * @see ActiveRecordInterface::update()
  */
 final class BeforeUpdate extends AbstractEvent
 {
     /**
      * @param ActiveRecordInterface $model The model being updated.
-     * @param array|null &$properties The properties that will be used for the update operation.
+     * @param array|null &$properties List of property names or name-values pairs that need to be updated.
+     * If name-value pairs are specified, the values will be used for update.
+     * If `null`, the properties will be taken from the model.
      */
     public function __construct(ActiveRecordInterface $model, public ?array &$properties)
     {

src/Event/BeforeUpsert.php

@@ -8,7 +8,7 @@
 
 /**
  * Event triggered before the model is upserted (inserted or updated) in the database.
- * It allows to modify properties that will be used for {@see ActiveRecordInterface::upsert()} operation.
+ * It allows modifying properties that will be used for {@see ActiveRecordInterface::upsert()} operation.
  *
  * @see ActiveRecordInterface::upsert()
  */