From 58efbb45bce132156f5bd86288fde8f2b1858531 Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Thu, 30 Jul 2020 12:38:15 -0400
Subject: [PATCH] Improve docs for APIv4 Save action

---
 Civi/Api4/Generic/AbstractSaveAction.php | 9 ++++++++-
 Civi/Api4/Generic/BasicSaveAction.php    | 8 ++------
 Civi/Api4/Generic/DAOSaveAction.php      | 6 +-----
 3 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/Civi/Api4/Generic/AbstractSaveAction.php b/Civi/Api4/Generic/AbstractSaveAction.php
index 953f6c59c9..b12dc33204 100644
--- a/Civi/Api4/Generic/AbstractSaveAction.php
+++ b/Civi/Api4/Generic/AbstractSaveAction.php
@@ -20,7 +20,14 @@
 namespace Civi\Api4\Generic;
 
 /**
- * Base class for all `Save` api actions.
+ * Create or update one or more $ENTITIES.
+ *
+ * Pass an array of one or more $ENTITY to save in the `records` param.
+ *
+ * If creating more than one $ENTITY with similar values, use the `defaults` param.
+ *
+ * Set `reload` if you need the api to return complete records for each saved $ENTITY
+ * (including values that were unchanged in from updated $ENTITIES).
  *
  * @method $this setRecords(array $records) Set array of records to be saved.
  * @method array getRecords()
diff --git a/Civi/Api4/Generic/BasicSaveAction.php b/Civi/Api4/Generic/BasicSaveAction.php
index 4ddb4234df..c1316ede97 100644
--- a/Civi/Api4/Generic/BasicSaveAction.php
+++ b/Civi/Api4/Generic/BasicSaveAction.php
@@ -22,11 +22,7 @@ namespace Civi\Api4\Generic;
 use Civi\API\Exception\NotImplementedException;
 
 /**
- * $ACTION one or more $ENTITIES.
- *
- * If saving more than one new $ENTITY with similar values, use the `defaults` parameter.
- *
- * Set `reload` if you need the api to return complete $ENTITY records.
+ * @inheritDoc
  */
 class BasicSaveAction extends AbstractSaveAction {
 
@@ -37,7 +33,7 @@ class BasicSaveAction extends AbstractSaveAction {
   private $setter;
 
   /**
-   * Basic Create constructor.
+   * Basic Save constructor.
    *
    * @param string $entityName
    * @param string $actionName
diff --git a/Civi/Api4/Generic/DAOSaveAction.php b/Civi/Api4/Generic/DAOSaveAction.php
index c6d0d36aa8..a3d8a288f5 100644
--- a/Civi/Api4/Generic/DAOSaveAction.php
+++ b/Civi/Api4/Generic/DAOSaveAction.php
@@ -20,11 +20,7 @@
 namespace Civi\Api4\Generic;
 
 /**
- * Create or update one or more $ENTITIES.
- *
- * If creating more than one $ENTITY with similar values, use the `defaults` param.
- *
- * Set `reload` if you need the api to return complete records for each saved $ENTITY.
+ * @inheritDoc
  */
 class DAOSaveAction extends AbstractSaveAction {
   use Traits\DAOActionTrait;
-- 
2.25.1