APIv4 - Variable substution in docblocks

Civi/Api4/Action/Entity/Get.php

@@ -132,7 +132,7 @@ private function plainTextify($input) {
    */
   private function addDocs(&$entity) {
     $reflection = new \ReflectionClass("\\Civi\\Api4\\" . $entity['name']);
-    $entity += ReflectionUtils::getCodeDocs($reflection);
+    $entity += ReflectionUtils::getCodeDocs($reflection, NULL, ['$ENTITY' => $entity['name']]);
     unset($entity['package'], $entity['method']);
   }
 

Civi/Api4/Action/GetActions.php

@@ -27,7 +27,9 @@
 use Civi\Api4\Utils\ReflectionUtils;
 
 /**
- * Get actions for an entity with a list of accepted params
+ * Get all API actions for the $ENTITY entity.
+ *
+ * Includes a list of accepted parameters for each action, descriptions and other documentation.
  */
 class GetActions extends BasicGetAction {
 
@@ -86,13 +88,18 @@ private function loadAction($actionName, $method = NULL) {
         if (is_object($action)) {
           $this->_actions[$actionName] = ['name' => $actionName];
           if ($this->_isFieldSelected('description', 'comment', 'see')) {
+            $vars = ['$ENTITY' => $this->getEntityName(), '$ACTION' => $actionName];
             // Docblock from action class
-            $actionDocs = ReflectionUtils::getCodeDocs($action->reflect());
+            $actionDocs = ReflectionUtils::getCodeDocs($action->reflect(), NULL, $vars);
             unset($actionDocs['method']);
             // Docblock from action factory function in entity class. This takes precedence since most action classes are generic.
             if ($method) {
-              $methodDocs = ReflectionUtils::getCodeDocs($method, 'Method');
-              $actionDocs = $methodDocs + $actionDocs;
+              $methodDocs = ReflectionUtils::getCodeDocs($method, 'Method', $vars);
+              // Allow method doc to inherit class doc
+              if (strpos($method->getDocComment(), '@inheritDoc') !== FALSE && !empty($methodDocs['comment']) && !empty($actionDocs['comment'])) {
+                $methodDocs['comment'] .= "\n\n" . $actionDocs['comment'];
+              }
+              $actionDocs = array_filter($methodDocs) + $actionDocs;
             }
             $this->_actions[$actionName] += $actionDocs;
           }

Civi/Api4/Generic/AbstractAction.php

@@ -270,10 +270,19 @@ public function getParams() {
   public function getParamInfo($param = NULL) {
     if (!isset($this->_paramInfo)) {
       $defaults = $this->getParamDefaults();
+      $vars = [
+        '$ENTITY' => $this->getEntityName(),
+        '$ACTION' => $this->getActionName(),
+      ];
+      // For actions like "getFields" and "getActions" they are not getting the entity itself.
+      // So generic docs will make more sense like this:
+      if (substr($vars['$ACTION'], 0, 3) === 'get' && substr($vars['$ACTION'], -1) === 's') {
+        $vars['$ENTITY'] = lcfirst(substr($vars['$ACTION'], 3, -1));
+      }
       foreach ($this->reflect()->getProperties(\ReflectionProperty::IS_PROTECTED) as $property) {
         $name = $property->getName();
         if ($name != 'version' && $name[0] != '_') {
-          $this->_paramInfo[$name] = ReflectionUtils::getCodeDocs($property, 'Property');
+          $this->_paramInfo[$name] = ReflectionUtils::getCodeDocs($property, 'Property', $vars);
           $this->_paramInfo[$name]['default'] = $defaults[$name];
         }
       }

Civi/Api4/Generic/AbstractBatchAction.php

@@ -31,7 +31,7 @@
 abstract class AbstractBatchAction extends AbstractQueryAction {
 
   /**
-   * Criteria for selecting items to process.
+   * Criteria for selecting $ENTITYs to process.
    *
    * @var array
    * @required

Civi/Api4/Generic/AbstractCreateAction.php

@@ -22,7 +22,7 @@
 namespace Civi\Api4\Generic;
 
 /**
- * Base class for all "Create" api actions.
+ * Base class for all `Create` api actions.
  *
  * @method $this setValues(array $values) Set all field values from an array of key => value pairs.
  * @method array getValues() Get field values.
@@ -32,7 +32,7 @@
 abstract class AbstractCreateAction extends AbstractAction {
 
   /**
-   * Field values to set
+   * Field values to set for the new $ENTITY.
    *
    * @var array
    */

Civi/Api4/Generic/AbstractGetAction.php

@@ -24,7 +24,7 @@
 use Civi\Api4\Utils\SelectUtil;
 
 /**
- * Base class for all "Get" api actions.
+ * Base class for all `Get` api actions.
  *
  * @package Civi\Api4\Generic
  *
@@ -34,12 +34,12 @@
 abstract class AbstractGetAction extends AbstractQueryAction {
 
   /**
-   * Fields to return. Defaults to all fields `["*"]`.
+   * Fields to return for each $ENTITY. Defaults to all fields `[*]`.
    *
    * Use the * wildcard by itself to select all available fields, or use it to match similarly-named fields.
    * E.g. `is_*` will match fields named is_primary, is_active, etc.
    *
-   * Set to `["row_count"]` to return only the number of items found.
+   * Set to `["row_count"]` to return only the number of $ENTITYs found.
    *
    * @var array
    */

Civi/Api4/Generic/AbstractQueryAction.php

@@ -22,7 +22,7 @@
 namespace Civi\Api4\Generic;
 
 /**
- * Base class for all actions that need to fetch records (Get, Update, Delete, etc)
+ * Base class for all actions that need to fetch records (`Get`, `Update`, `Delete`, etc.).
  *
  * @package Civi\Api4\Generic
  *
@@ -38,27 +38,29 @@
 abstract class AbstractQueryAction extends AbstractAction {
 
   /**
-   * Criteria for selecting items.
-   *
-   * $example->addWhere('contact_type', 'IN', array('Individual', 'Household'))
+   * Criteria for selecting $ENTITYs.
    *
+   * ```php
+   * $example->addWhere('contact_type', 'IN', ['Individual', 'Household'])
+   * ```
    * @var array
    */
   protected $where = [];
 
   /**
-   * Array of field(s) to use in ordering the results
+   * Array of field(s) to use in ordering the results.
    *
    * Defaults to id ASC
    *
+   * ```php
    * $example->addOrderBy('sort_name', 'ASC')
-   *
+   * ```
    * @var array
    */
   protected $orderBy = [];
 
   /**
-   * Maximum number of results to return.
+   * Maximum number of $ENTITYs to return.
    *
    * Defaults to unlimited.
    *
@@ -70,9 +72,9 @@ abstract class AbstractQueryAction extends AbstractAction {
   protected $limit = 0;
 
   /**
-   * Zero-based index of first result to return.
+   * Zero-based index of first $ENTITY to return.
    *
-   * Defaults to "0" - first record.
+   * Defaults to "0" - first $ENTITY found.
    *
    * @var int
    */

Civi/Api4/Generic/AbstractSaveAction.php

@@ -22,7 +22,7 @@
 namespace Civi\Api4\Generic;
 
 /**
- * Base class for all "Save" api actions.
+ * Base class for all `Save` api actions.
  *
  * @method $this setRecords(array $records) Set array of records to be saved.
  * @method array getRecords()
@@ -36,9 +36,9 @@
 abstract class AbstractSaveAction extends AbstractAction {
 
   /**
-   * Array of records.
+   * Array of $ENTITYs to save.
    *
-   * Should be in the same format as returned by Get.
+   * Should be in the same format as returned by `Get`.
    *
    * @var array
    * @required
@@ -48,18 +48,18 @@ abstract class AbstractSaveAction extends AbstractAction {
   /**
    * Array of default values.
    *
-   * These defaults will be applied to all records unless they specify otherwise.
+   * These defaults will be applied to all $ENTITYs unless they specify otherwise.
    *
    * @var array
    */
   protected $defaults = [];
 
   /**
-   * Reload records after saving.
+   * Reload $ENTITYs after saving.
    *
-   * By default this api typically returns partial records containing only the fields
-   * that were updated. Set reload to TRUE to do an additional lookup after saving
-   * to return complete records.
+   * By default this action typically returns partial records containing only the fields
+   * that were updated. Set `reload` to `true` to do an additional lookup after saving
+   * to return complete values for every $ENTITY.
    *
    * @var bool
    */

Civi/Api4/Generic/AbstractUpdateAction.php

@@ -22,7 +22,7 @@
 namespace Civi\Api4\Generic;
 
 /**
- * Base class for all "Update" api actions
+ * Base class for all `Update` api actions
  *
  * @method $this setValues(array $values) Set all field values from an array of key => value pairs.
  * @method array getValues() Get field values.
@@ -42,10 +42,10 @@ abstract class AbstractUpdateAction extends AbstractBatchAction {
   protected $values = [];
 
   /**
-   * Reload objects after saving.
+   * Reload $ENTITYs after saving.
    *
-   * Setting to TRUE will load complete records and return them as the api result.
-   * If FALSE the api usually returns only the fields specified to be updated.
+   * Setting to `true` will load complete records and return them as the api result.
+   * If `false` the api usually returns only the fields specified to be updated.
    *
    * @var bool
    */
@@ -61,7 +61,8 @@ public function getValue(string $fieldName) {
   }
 
   /**
-   * Add an item to the values array
+   * Add an item to the values array.
+   *
    * @param string $fieldName
    * @param mixed $value
    * @return $this

Civi/Api4/Generic/BasicBatchAction.php

@@ -24,12 +24,9 @@
 use Civi\API\Exception\NotImplementedException;
 
 /**
- * Basic action for deleting or performing some other task with a set of records.  Ex:
+ * $ACTION one or more $ENTITYs.
  *
- * $myAction = new BasicBatchAction('Entity', 'action', function($item) {
- *   // Do something with $item
- *   $return $item;
- * });
+ * $ENTITYs are selected based on criteria specified in `where` parameter (required).
  *
  * @package Civi\Api4\Generic
  */
@@ -45,6 +42,13 @@ class BasicBatchAction extends AbstractBatchAction {
   /**
    * BasicBatchAction constructor.
    *
+   * ```php
+   * $myAction = new BasicBatchAction($entityName, $actionName, function($item) {
+   *   // Do something with $item
+   *   $return $item;
+   * });
+   * ```
+   *
    * @param string $entityName
    * @param string $actionName
    * @param string|array $select

Civi/Api4/Generic/BasicCreateAction.php

@@ -24,9 +24,10 @@
 use Civi\API\Exception\NotImplementedException;
 
 /**
- * Create a new object from supplied values.
+ * Create a new $ENTITY from supplied values.
  *
- * This function will create 1 new object. It cannot be used to update existing objects. Use the Update or Replace actions for that.
+ * This action will create 1 new $ENTITY.
+ * It cannot be used to update existing $ENTITYs; use the `Update` or `Replace` actions for that.
  */
 class BasicCreateAction extends AbstractCreateAction {
 

Civi/Api4/Generic/BasicGetAction.php

@@ -24,9 +24,9 @@
 use Civi\API\Exception\NotImplementedException;
 
 /**
- * Retrieve items based on criteria specified in the 'where' param.
+ * Retrieve $ENTITYs based on criteria specified in the `where` parameter.
  *
- * Use the 'select' param to determine which fields are returned, defaults to *.
+ * Use the `select` param to determine which fields are returned, defaults to `[*]`.
  */
 class BasicGetAction extends AbstractGetAction {
   use Traits\ArrayQueryActionTrait;

Civi/Api4/Generic/BasicGetFieldsAction.php

@@ -25,12 +25,12 @@
 use Civi\Api4\Utils\ActionUtil;
 
 /**
- * Get information about an entity's fields.
+ * Lists information about fields for the $ENTITY entity.
  *
  * This field information is also known as "metadata."
  *
  * Note that different actions may support different lists of fields.
- * By default this will fetch the field list relevant to Get,
+ * By default this will fetch the field list relevant to `get`,
  * but a different list may be returned if you specify another action.
  *
  * @method $this setLoadOptions(bool $value)

Civi/Api4/Generic/BasicReplaceAction.php

@@ -25,21 +25,28 @@
 use Civi\Api4\Utils\ActionUtil;
 
 /**
- * Given a set of records, will appropriately update the database.
+ * Replaces an existing set of $ENTITYs with a new one.
  *
- * @method $this setRecords(array $records) Array of records.
+ * This will select a group of existing $ENTITYs based on the `where` parameter.
+ * Each will be compared with the $ENTITYs passed in as `records`:
+ *
+ *  - $ENTITYs in `records` that don't already exist will be created.
+ *  - Existing $ENTITYs that are included in `records` will be updated.
+ *  - Existing $ENTITYs that are omitted from `records` will be deleted.
+ *
+ * @method $this setRecords(array $records) Set array of records.
  * @method array getRecords()
- * @method $this setDefaults(array $defaults) Array of defaults.
+ * @method $this setDefaults(array $defaults) Set array of defaults.
  * @method array getDefaults()
  * @method $this setReload(bool $reload) Specify whether complete objects will be returned after saving.
  * @method bool getReload()
  */
 class BasicReplaceAction extends AbstractBatchAction {
 
   /**
-   * Array of records.
+   * Array of $ENTITY records.
    *
-   * Should be in the same format as returned by Get.
+   * Should be in the same format as returned by `Get`.
    *
    * @var array
    * @required
@@ -49,18 +56,21 @@ class BasicReplaceAction extends AbstractBatchAction {
   /**
    * Array of default values.
    *
-   * Will be merged into $records before saving.
+   * Will be merged into `records` before saving.
+   *
+   * **Note:** Values from the `where` clause that use the `=` operator are _also_ saved into each record;
+   * those do not need to be repeated here.
    *
    * @var array
    */
   protected $defaults = [];
 
   /**
-   * Reload records after saving.
+   * Reload $ENTITYs after saving.
    *
-   * By default this api typically returns partial records containing only the fields
-   * that were updated. Set reload to TRUE to do an additional lookup after saving
-   * to return complete records.
+   * By default this action typically returns partial records containing only the fields
+   * that were updated. Set `reload` to `true` to do an additional lookup after saving
+   * to return complete values for every $ENTITY.
    *
    * @var bool
    */

Civi/Api4/Generic/BasicSaveAction.php

@@ -25,11 +25,11 @@
 use Civi\Api4\Utils\ActionUtil;
 
 /**
- * Create or update one or more records.
+ * $ACTION one or more $ENTITYs.
  *
- * If creating more than one record with similar values, use the "defaults" param.
+ * If saving more than one new $ENTITY with similar values, use the `defaults` parameter.
  *
- * Set "reload" if you need the api to return complete records.
+ * Set `reload` if you need the api to return complete $ENTITY records.
  */
 class BasicSaveAction extends AbstractSaveAction {