From c2adedc1d5215d0ba9826bf9e719edf115901193 Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Wed, 29 Jan 2020 11:43:55 -0500
Subject: [PATCH] APIv4 - Add docblocks to base classes

---
 Civi/Api4/Generic/AbstractAction.php |  9 +++++++++
 Civi/Api4/Generic/AbstractEntity.php | 15 +++++++++------
 Civi/Api4/Generic/Result.php         |  8 ++++++++
 3 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/Civi/Api4/Generic/AbstractAction.php b/Civi/Api4/Generic/AbstractAction.php
index 31a9fd4a29..310df486e5 100644
--- a/Civi/Api4/Generic/AbstractAction.php
+++ b/Civi/Api4/Generic/AbstractAction.php
@@ -26,6 +26,15 @@ use Civi\Api4\Utils\ActionUtil;
 /**
  * Base class for all api actions.
  *
+ * An api Action object stores the parameters of the api call, and defines a _run function to execute the action.
+ *
+ * Every `protected` class var is considered a parameter (unless it starts with an underscore).
+ *
+ * Adding a `protected` var to your Action named e.g. `$thing` will automatically:
+ *  - Provide a getter/setter (via `__call` MagicMethod) named `getThing()` and `setThing()`.
+ *  - Expose the param in the Api Explorer (be sure to add a doc-block as it displays in the help panel).
+ *  - Require a value for the param if you add the "@required" annotation.
+ *
  * @method $this setCheckPermissions(bool $value) Enable/disable permission checks
  * @method bool getCheckPermissions()
  * @method $this setDebug(bool $value) Enable/disable debug output
diff --git a/Civi/Api4/Generic/AbstractEntity.php b/Civi/Api4/Generic/AbstractEntity.php
index cdcd6dd100..d05697a84e 100644
--- a/Civi/Api4/Generic/AbstractEntity.php
+++ b/Civi/Api4/Generic/AbstractEntity.php
@@ -30,17 +30,20 @@ use Civi\API\Exception\NotImplementedException;
  *
  * The recommended way to create a non-DAO-based api is to extend this class
  * and then add a getFields function and any other actions you wish, e.g.
- * - a get() function which returns BasicGetAction using your custom getter callback
- * - a create() function which returns BasicCreateAction using your custom setter callback
- * - an update() function which returns BasicUpdateAction using your custom setter callback
- * - a delete() function which returns BasicBatchAction using your custom delete callback
+ * - a get() function which returns BasicGetAction using your custom getter callback.
+ * - a create() function which returns BasicCreateAction using your custom setter callback.
+ * - a save() function which returns BasicSaveAction using your custom setter callback.
+ * - an update() function which returns BasicUpdateAction using your custom setter callback.
+ * - a delete() function which returns BasicBatchAction using your custom delete callback.
  * - a replace() function which returns BasicReplaceAction (no callback needed but
- *   depends on the existence of get, create, update & delete actions)
+ *   depends on the existence of get, save & delete actions).
  *
  * Note that you can use the same setter callback function for update as create -
  * that function can distinguish between new & existing records by checking if the
  * unique identifier has been set (identifier field defaults to "id" but you can change
- * that when constructing BasicUpdateAction)
+ * that when constructing BasicUpdateAction).
+ *
+ * @see https://lab.civicrm.org/extensions/api4example
  */
 abstract class AbstractEntity {
 
diff --git a/Civi/Api4/Generic/Result.php b/Civi/Api4/Generic/Result.php
index c32bfa5749..fa6561a330 100644
--- a/Civi/Api4/Generic/Result.php
+++ b/Civi/Api4/Generic/Result.php
@@ -13,6 +13,14 @@ namespace Civi\Api4\Generic;
 
 /**
  * Container for api results.
+ *
+ * The Result object has three functions:
+ *
+ *  1. Store the results of the API call (accessible via ArrayAccess).
+ *  2. Store metadata like the Entity & Action names.
+ *     - Note: some actions extend the Result object to store extra metadata.
+ *       For example, BasicReplaceAction returns ReplaceResult which includes the additional $deleted property to list any items deleted by the operation.
+ *  3. Provide convenience methods like `$result->first()` and `$result->indexBy($field)`.
  */
 class Result extends \ArrayObject {
   /**
-- 
2.25.1