Clearer docblock description of the defaults param

diff --git a/Civi/Api4/Generic/AbstractSaveAction.php b/Civi/Api4/Generic/AbstractSaveAction.php
index 062beb792661623d37a7f37c6a17caa33ee58ad2..a644cc459ca7724fb89a87e99791e13e88f35c1c 100644 (file)
--- a/Civi/Api4/Generic/AbstractSaveAction.php
+++ b/Civi/Api4/Generic/AbstractSaveAction.php
@@ -48,7 +48,9 @@ abstract class AbstractSaveAction extends AbstractAction {
   /**
    * Array of default values.
    *
-   * These defaults will be applied to all $ENTITYs unless they specify otherwise.
+   * These defaults will be merged into every $ENTITY in `records` before saving.
+   * Values set in `records` will override these defaults if set in both places,
+   * but updating existing $ENTITYs will overwrite current values with these defaults.
    *
    * @var array
    */

diff --git a/Civi/Api4/Generic/BasicReplaceAction.php b/Civi/Api4/Generic/BasicReplaceAction.php
index 8ae267cf597e24d8fbafc20ebfe11bd0f78545ba..10edcaa9ec5be90e65b7558b7eed664c4d89591a 100644 (file)
--- a/Civi/Api4/Generic/BasicReplaceAction.php
+++ b/Civi/Api4/Generic/BasicReplaceAction.php
@@ -56,9 +56,11 @@ class BasicReplaceAction extends AbstractBatchAction {
   /**
    * Array of default values.
    *
-   * Will be merged into `records` before saving.
+   * These defaults will be merged into every $ENTITY in `records` before saving.
+   * Values set in `records` will override these defaults if set in both places,
+   * but updating existing $ENTITYs will overwrite current values with these defaults.
    *
-   * **Note:** Values from the `where` clause that use the `=` operator are _also_ saved into each record;
+   * **Note:** Values from the `where` clause that use the `=` operator are _also_ treated as default values;
    * those do not need to be repeated here.
    *
    * @var array