From: Coleman Watts Date: Fri, 31 Jan 2020 22:06:41 +0000 (-0500) Subject: APIv4 - Variable substution in docblocks X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=fc95d9a569ece20b0377610923be9c09f82321d5;p=civicrm-core.git APIv4 - Variable substution in docblocks Replaces $ENTITY and $ACTION in docblocks to improve help text in the api explorer. --- diff --git a/Civi/Api4/Action/Entity/Get.php b/Civi/Api4/Action/Entity/Get.php index 37e59f2edc..b8e0763ee2 100644 --- a/Civi/Api4/Action/Entity/Get.php +++ b/Civi/Api4/Action/Entity/Get.php @@ -132,7 +132,7 @@ class Get extends \Civi\Api4\Generic\BasicGetAction { */ 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']); } diff --git a/Civi/Api4/Action/GetActions.php b/Civi/Api4/Action/GetActions.php index 46dae61031..0ce201b797 100644 --- a/Civi/Api4/Action/GetActions.php +++ b/Civi/Api4/Action/GetActions.php @@ -27,7 +27,9 @@ use Civi\Api4\Utils\ActionUtil; 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 @@ class GetActions extends BasicGetAction { 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; } diff --git a/Civi/Api4/Generic/AbstractAction.php b/Civi/Api4/Generic/AbstractAction.php index d4a0ed9371..5138c1c87a 100644 --- a/Civi/Api4/Generic/AbstractAction.php +++ b/Civi/Api4/Generic/AbstractAction.php @@ -270,10 +270,19 @@ abstract class AbstractAction implements \ArrayAccess { 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]; } } diff --git a/Civi/Api4/Generic/AbstractBatchAction.php b/Civi/Api4/Generic/AbstractBatchAction.php index 05c078b587..89fe786eea 100644 --- a/Civi/Api4/Generic/AbstractBatchAction.php +++ b/Civi/Api4/Generic/AbstractBatchAction.php @@ -31,7 +31,7 @@ namespace Civi\Api4\Generic; abstract class AbstractBatchAction extends AbstractQueryAction { /** - * Criteria for selecting items to process. + * Criteria for selecting $ENTITYs to process. * * @var array * @required diff --git a/Civi/Api4/Generic/AbstractCreateAction.php b/Civi/Api4/Generic/AbstractCreateAction.php index 416e15f056..ea9d3cdb9d 100644 --- a/Civi/Api4/Generic/AbstractCreateAction.php +++ b/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 @@ namespace Civi\Api4\Generic; abstract class AbstractCreateAction extends AbstractAction { /** - * Field values to set + * Field values to set for the new $ENTITY. * * @var array */ diff --git a/Civi/Api4/Generic/AbstractGetAction.php b/Civi/Api4/Generic/AbstractGetAction.php index 7a32a54da6..0f4f37e395 100644 --- a/Civi/Api4/Generic/AbstractGetAction.php +++ b/Civi/Api4/Generic/AbstractGetAction.php @@ -24,7 +24,7 @@ namespace Civi\Api4\Generic; 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 @@ use Civi\Api4\Utils\SelectUtil; 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 */ diff --git a/Civi/Api4/Generic/AbstractQueryAction.php b/Civi/Api4/Generic/AbstractQueryAction.php index 96d442ecc8..74aa495b82 100644 --- a/Civi/Api4/Generic/AbstractQueryAction.php +++ b/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 @@ namespace Civi\Api4\Generic; 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 */ diff --git a/Civi/Api4/Generic/AbstractSaveAction.php b/Civi/Api4/Generic/AbstractSaveAction.php index a3cc132767..062beb7926 100644 --- a/Civi/Api4/Generic/AbstractSaveAction.php +++ b/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 @@ namespace Civi\Api4\Generic; 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 */ diff --git a/Civi/Api4/Generic/AbstractUpdateAction.php b/Civi/Api4/Generic/AbstractUpdateAction.php index b3fe4d8635..6c6ca176cb 100644 --- a/Civi/Api4/Generic/AbstractUpdateAction.php +++ b/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 @@ abstract class AbstractUpdateAction extends AbstractBatchAction { } /** - * Add an item to the values array + * Add an item to the values array. + * * @param string $fieldName * @param mixed $value * @return $this diff --git a/Civi/Api4/Generic/BasicBatchAction.php b/Civi/Api4/Generic/BasicBatchAction.php index 259b68cbe8..860e4273a5 100644 --- a/Civi/Api4/Generic/BasicBatchAction.php +++ b/Civi/Api4/Generic/BasicBatchAction.php @@ -24,12 +24,9 @@ namespace Civi\Api4\Generic; 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 diff --git a/Civi/Api4/Generic/BasicCreateAction.php b/Civi/Api4/Generic/BasicCreateAction.php index ff26bd315c..e06c869423 100644 --- a/Civi/Api4/Generic/BasicCreateAction.php +++ b/Civi/Api4/Generic/BasicCreateAction.php @@ -24,9 +24,10 @@ namespace Civi\Api4\Generic; 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 { diff --git a/Civi/Api4/Generic/BasicGetAction.php b/Civi/Api4/Generic/BasicGetAction.php index 67f3b0a0ed..0a9e047daa 100644 --- a/Civi/Api4/Generic/BasicGetAction.php +++ b/Civi/Api4/Generic/BasicGetAction.php @@ -24,9 +24,9 @@ namespace Civi\Api4\Generic; 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; diff --git a/Civi/Api4/Generic/BasicGetFieldsAction.php b/Civi/Api4/Generic/BasicGetFieldsAction.php index 19f548e6a0..ae11f65f48 100644 --- a/Civi/Api4/Generic/BasicGetFieldsAction.php +++ b/Civi/Api4/Generic/BasicGetFieldsAction.php @@ -25,12 +25,12 @@ use Civi\API\Exception\NotImplementedException; 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) diff --git a/Civi/Api4/Generic/BasicReplaceAction.php b/Civi/Api4/Generic/BasicReplaceAction.php index 31f12a44ac..8ae267cf59 100644 --- a/Civi/Api4/Generic/BasicReplaceAction.php +++ b/Civi/Api4/Generic/BasicReplaceAction.php @@ -25,11 +25,18 @@ use Civi\API\Exception\NotImplementedException; 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() @@ -37,9 +44,9 @@ use Civi\Api4\Utils\ActionUtil; 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 */ diff --git a/Civi/Api4/Generic/BasicSaveAction.php b/Civi/Api4/Generic/BasicSaveAction.php index db08fb95a6..ba4c1a12df 100644 --- a/Civi/Api4/Generic/BasicSaveAction.php +++ b/Civi/Api4/Generic/BasicSaveAction.php @@ -25,11 +25,11 @@ use Civi\API\Exception\NotImplementedException; 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 { diff --git a/Civi/Api4/Generic/BasicUpdateAction.php b/Civi/Api4/Generic/BasicUpdateAction.php index 7e91570bdf..a7c8865f8c 100644 --- a/Civi/Api4/Generic/BasicUpdateAction.php +++ b/Civi/Api4/Generic/BasicUpdateAction.php @@ -24,9 +24,9 @@ namespace Civi\Api4\Generic; use Civi\API\Exception\NotImplementedException; /** - * Update one or more records with new values. + * Update one or more $ENTITY with new values. * - * Use the where clause (required) to select them. + * Use the `where` clause (required) to select them. */ class BasicUpdateAction extends AbstractUpdateAction { diff --git a/Civi/Api4/Generic/DAOCreateAction.php b/Civi/Api4/Generic/DAOCreateAction.php index 36b19a0a6d..59436c0d99 100644 --- a/Civi/Api4/Generic/DAOCreateAction.php +++ b/Civi/Api4/Generic/DAOCreateAction.php @@ -22,9 +22,10 @@ namespace Civi\Api4\Generic; /** - * 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 DAOCreateAction extends AbstractCreateAction { use Traits\DAOActionTrait; diff --git a/Civi/Api4/Generic/DAODeleteAction.php b/Civi/Api4/Generic/DAODeleteAction.php index 7398fdf3cb..83b39a38bf 100644 --- a/Civi/Api4/Generic/DAODeleteAction.php +++ b/Civi/Api4/Generic/DAODeleteAction.php @@ -22,7 +22,9 @@ namespace Civi\Api4\Generic; /** - * Delete one or more items, based on criteria specified in Where param (required). + * Delete one or more $ENTITYs. + * + * $ENTITYs are deleted based on criteria specified in `where` parameter (required). */ class DAODeleteAction extends AbstractBatchAction { use Traits\DAOActionTrait; diff --git a/Civi/Api4/Generic/DAOGetAction.php b/Civi/Api4/Generic/DAOGetAction.php index a6968a147f..da97a68d40 100644 --- a/Civi/Api4/Generic/DAOGetAction.php +++ b/Civi/Api4/Generic/DAOGetAction.php @@ -22,9 +22,9 @@ namespace Civi\Api4\Generic; /** - * 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 `[*]`. * * Perform joins on other related entities using a dot notation. */ @@ -32,9 +32,9 @@ class DAOGetAction extends AbstractGetAction { use Traits\DAOActionTrait; /** - * Fields to return. Defaults to all non-custom fields `["*"]`. + * Fields to return. Defaults to all non-custom fields `[*]`. * - * Use the dot notation to perform joins in the select clause, e.g. selecting `["*", "contact.*"]` from `Email::get()` + * Use the dot notation to perform joins in the select clause, e.g. selecting `['*', 'contact.*']` from `Email::get()` * will select all fields for the email + all fields for the related contact. * * @var array diff --git a/Civi/Api4/Generic/DAOSaveAction.php b/Civi/Api4/Generic/DAOSaveAction.php index cd91e53be1..ab4888a38a 100644 --- a/Civi/Api4/Generic/DAOSaveAction.php +++ b/Civi/Api4/Generic/DAOSaveAction.php @@ -22,11 +22,11 @@ namespace Civi\Api4\Generic; /** - * Create or update one or more records. + * Create or update one or more $ENTITYs. * - * If creating more than one record with similar values, use the "defaults" 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. + * Set `reload` if you need the api to return complete records for each saved $ENTITY. */ class DAOSaveAction extends AbstractSaveAction { use Traits\DAOActionTrait; diff --git a/Civi/Api4/Generic/DAOUpdateAction.php b/Civi/Api4/Generic/DAOUpdateAction.php index feff2f414b..b2768ee4d1 100644 --- a/Civi/Api4/Generic/DAOUpdateAction.php +++ b/Civi/Api4/Generic/DAOUpdateAction.php @@ -22,9 +22,9 @@ namespace Civi\Api4\Generic; /** - * Update one or more records with new values. + * Update one or more $ENTITY with new values. * - * Use the where clause (required) to select them. + * Use the `where` clause (required) to select them. */ class DAOUpdateAction extends AbstractUpdateAction { use Traits\DAOActionTrait; diff --git a/Civi/Api4/Utils/ReflectionUtils.php b/Civi/Api4/Utils/ReflectionUtils.php index 9cb4f6fb5d..4ff7d9775e 100644 --- a/Civi/Api4/Utils/ReflectionUtils.php +++ b/Civi/Api4/Utils/ReflectionUtils.php @@ -20,11 +20,16 @@ class ReflectionUtils { * @param \Reflector|\ReflectionClass $reflection * @param string $type * If we are not reflecting the class itself, specify "Method", "Property", etc. - * + * @param array $vars + * Variable substitutions to perform in the docblock * @return array */ - public static function getCodeDocs($reflection, $type = NULL) { - $docs = self::parseDocBlock($reflection->getDocComment()); + public static function getCodeDocs($reflection, $type = NULL, $vars = []) { + $comment = $reflection->getDocComment(); + if ($vars) { + $comment = str_replace(array_keys($vars), array_values($vars), $comment); + } + $docs = self::parseDocBlock($comment); // Recurse into parent functions if (isset($docs['inheritDoc']) || isset($docs['inheritdoc'])) { @@ -47,7 +52,7 @@ class ReflectionUtils { } if ($newReflection) { // Mix in - $additionalDocs = self::getCodeDocs($newReflection, $type); + $additionalDocs = self::getCodeDocs($newReflection, $type, $vars); if (!empty($docs['comment']) && !empty($additionalDocs['comment'])) { $docs['comment'] .= "\n\n" . $additionalDocs['comment']; } @@ -108,19 +113,26 @@ class ReflectionUtils { $info['params'][$param]['comment'] .= $line . "\n"; } elseif ($num == 1) { - $info['description'] = $line; + $info['description'] = ucfirst($line); } elseif (!$line) { if (isset($info['comment'])) { $info['comment'] .= "\n"; } + else { + $info['comment'] = NULL; + } + } + // For multi-line description. + elseif (count($info) === 1 && isset($info['description']) && substr($info['description'], -1) !== '.') { + $info['description'] .= ' ' . $line; } else { $info['comment'] = isset($info['comment']) ? "{$info['comment']}\n$line" : $line; } } if (isset($info['comment'])) { - $info['comment'] = trim($info['comment']); + $info['comment'] = rtrim($info['comment']); } return $info; } diff --git a/ang/api4Explorer/Explorer.html b/ang/api4Explorer/Explorer.html index e924625746..adb55b0807 100644 --- a/ang/api4Explorer/Explorer.html +++ b/ang/api4Explorer/Explorer.html @@ -120,9 +120,7 @@
See:
diff --git a/ang/api4Explorer/Explorer.js b/ang/api4Explorer/Explorer.js index a34f66460a..7a20910ba8 100644 --- a/ang/api4Explorer/Explorer.js +++ b/ang/api4Explorer/Explorer.js @@ -159,17 +159,30 @@ $scope.helpContent = helpContent; } else { $scope.helpTitle = title; - $scope.helpContent = convertMarkdown(content); + $scope.helpContent = formatHelp(content); } }; // Sets the static help text (which gets overridden by mousing over other elements) function setHelp(title, content) { $scope.helpTitle = helpTitle = title; - $scope.helpContent = helpContent = convertMarkdown(content); + $scope.helpContent = helpContent = formatHelp(content); } - function convertMarkdown(rawContent) { + // Convert plain-text help to markdown; replace variables and format links + function formatHelp(rawContent) { + function formatRefs(see) { + _.each(see, function(ref, idx) { + var match = ref.match(/^\\Civi\\Api4\\([a-zA-Z]+)$/); + if (match) { + ref = '#/explorer/' + match[1]; + } + if (ref[0] === '\\') { + ref = 'https://github.com/civicrm/civicrm-core/blob/master' + ref.replace(/\\/i, '/') + '.php'; + } + see[idx] = '' + see[idx] + ''; + }); + } var formatted = _.cloneDeep(rawContent); if (formatted.description) { formatted.description = marked(formatted.description); @@ -177,21 +190,10 @@ if (formatted.comment) { formatted.comment = marked(formatted.comment); } + formatRefs(formatted.see); return formatted; } - // Format the href for a @see help annotation - $scope.formatRef = function(see) { - var match = see.match(/^\\Civi\\Api4\\([a-zA-Z]+)$/); - if (match) { - return '#/explorer/' + match[1]; - } - if (see[0] === '\\') { - return 'https://github.com/civicrm/civicrm-core/blob/master' + see.replace(/\\/i, '/') + '.php'; - } - return see; - }; - $scope.fieldHelp = function(fieldName) { var field = getField(fieldName, $scope.entity, $scope.action); if (!field) { diff --git a/tests/phpunit/api/v4/Entity/ParticipantTest.php b/tests/phpunit/api/v4/Entity/ParticipantTest.php index 875cbdb1ba..6f243c4fae 100644 --- a/tests/phpunit/api/v4/Entity/ParticipantTest.php +++ b/tests/phpunit/api/v4/Entity/ParticipantTest.php @@ -47,10 +47,10 @@ class ParticipantTest extends UnitTestCase { ->indexBy('name'); $getParams = $result['get']['params']; - $whereDescription = 'Criteria for selecting items.'; + $whereDescription = 'Criteria for selecting Participants'; $this->assertEquals(TRUE, $getParams['checkPermissions']['default']); - $this->assertEquals($whereDescription, $getParams['where']['description']); + $this->assertContains($whereDescription, $getParams['where']['description']); } public function testGet() { diff --git a/tests/phpunit/api/v4/Mock/MockV4ReflectionBase.php b/tests/phpunit/api/v4/Mock/MockV4ReflectionBase.php index de6bd7e91a..2eb9ce07f3 100644 --- a/tests/phpunit/api/v4/Mock/MockV4ReflectionBase.php +++ b/tests/phpunit/api/v4/Mock/MockV4ReflectionBase.php @@ -32,7 +32,7 @@ class MockV4ReflectionBase { /** * This is the foo property. * - * In general, you can do nothing with it. + * - In general, you can do nothing with it. * * @var array */ diff --git a/tests/phpunit/api/v4/Mock/MockV4ReflectionGrandchild.php b/tests/phpunit/api/v4/Mock/MockV4ReflectionGrandchild.php index e5f7742ba6..3e22ef59aa 100644 --- a/tests/phpunit/api/v4/Mock/MockV4ReflectionGrandchild.php +++ b/tests/phpunit/api/v4/Mock/MockV4ReflectionGrandchild.php @@ -22,11 +22,12 @@ namespace api\v4\Mock; /** - * Grandchild class + * Grandchild class for $ENTITY, + * with a 2-line description! * - * This is an extended description. + * This is an extended comment. * - * There is a line break in this description. + * There is a line break in this comment. * * @inheritdoc */ diff --git a/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php b/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php index 494e4d5993..fb3b644585 100644 --- a/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php +++ b/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php @@ -36,14 +36,14 @@ class ReflectionUtilsTest extends UnitTestCase { public function testGetDocBlockForClass() { $grandChild = new MockV4ReflectionGrandchild(); $reflection = new \ReflectionClass($grandChild); - $doc = ReflectionUtils::getCodeDocs($reflection); + $doc = ReflectionUtils::getCodeDocs($reflection, NULL, ['$ENTITY' => "Test"]); $this->assertEquals(TRUE, $doc['internal']); - $this->assertEquals('Grandchild class', $doc['description']); + $this->assertEquals('Grandchild class for Test, with a 2-line description!', $doc['description']); - $expectedComment = 'This is an extended description. + $expectedComment = 'This is an extended comment. -There is a line break in this description. + There is a line break in this comment. This is the base class.'; @@ -59,7 +59,7 @@ This is the base class.'; $doc = ReflectionUtils::getCodeDocs($reflection->getProperty('foo'), 'Property'); $this->assertEquals('This is the foo property.', $doc['description']); - $this->assertEquals("In the child class, foo has been barred.\n\nIn general, you can do nothing with it.", $doc['comment']); + $this->assertEquals("In the child class, foo has been barred.\n\n - In general, you can do nothing with it.", $doc['comment']); } public function docBlockExamples() {