From 0493ec47eb10a4ca6a4cca092b6e669c8d2f1d16 Mon Sep 17 00:00:00 2001 From: Coleman Watts Date: Fri, 24 Jan 2020 13:09:41 -0500 Subject: [PATCH] Add @see annoations to api4 docblocks and show as links in api explorer --- Civi/Api4/ACL.php | 14 ++++++++------ Civi/Api4/Action/Entity/Get.php | 6 +++++- Civi/Api4/ActionSchedule.php | 1 + Civi/Api4/Activity.php | 1 + Civi/Api4/ActivityContact.php | 1 + Civi/Api4/Campaign.php | 1 + Civi/Api4/Contact.php | 1 + Civi/Api4/ContactType.php | 2 ++ Civi/Api4/CustomField.php | 2 ++ Civi/Api4/CustomGroup.php | 2 ++ Civi/Api4/Domain.php | 2 ++ Civi/Api4/Entity.php | 2 ++ Civi/Api4/EntityTag.php | 3 ++- Civi/Api4/Event.php | 2 ++ Civi/Api4/Event/Events.php | 2 +- Civi/Api4/Group.php | 3 ++- Civi/Api4/GroupContact.php | 3 ++- Civi/Api4/GroupNesting.php | 2 ++ Civi/Api4/GroupOrganization.php | 3 +++ Civi/Api4/Mapping.php | 1 - Civi/Api4/MappingField.php | 3 ++- Civi/Api4/Navigation.php | 1 - Civi/Api4/OptionGroup.php | 1 + Civi/Api4/OptionValue.php | 1 + Civi/Api4/Participant.php | 1 - Civi/Api4/PaymentProcessor.php | 2 ++ Civi/Api4/PaymentProcessorType.php | 2 ++ Civi/Api4/Provider/ActionObjectProvider.php | 2 +- Civi/Api4/Relationship.php | 2 ++ Civi/Api4/RelationshipType.php | 2 ++ Civi/Api4/Route.php | 11 +++++++++++ Civi/Api4/Service/Spec/SpecGatherer.php | 2 +- Civi/Api4/Setting.php | 1 + Civi/Api4/StatusPreference.php | 2 ++ Civi/Api4/Tag.php | 1 + Civi/Api4/UFField.php | 1 + Civi/Api4/UFGroup.php | 1 + Civi/Api4/UFJoin.php | 1 + Civi/Api4/Utils/ReflectionUtils.php | 5 ++++- ang/api4Explorer/Explorer.html | 10 +++++++++- ang/api4Explorer/Explorer.js | 19 ++++++++++++++++--- api/api.php | 4 ++-- .../api/v4/Utils/ReflectionUtilsTest.php | 9 +++++---- 43 files changed, 110 insertions(+), 28 deletions(-) diff --git a/Civi/Api4/ACL.php b/Civi/Api4/ACL.php index 7e037a5b38..5ac059f613 100644 --- a/Civi/Api4/ACL.php +++ b/Civi/Api4/ACL.php @@ -22,15 +22,17 @@ namespace Civi\Api4; /** - * ACL Entity. + * ACL (Access Control List). * - * This entity holds the ACL informatiom. With this entity you add/update/delete an ACL permission which consists of - * an Operation (e.g. 'View' or 'Edit'), a set of Data that the operation can be performed on (e.g. a group of contacts), - * and a Role that has permission to do this operation. For more info refer to - * https://docs.civicrm.org/user/en/latest/initial-set-up/permissions-and-access-control for more info. + * An ACL record consists of: * - * Creating a new ACL requires at minimum a entity table, entity ID and object_table + * - an Operation (e.g. 'View' or 'Edit') + * - a set of Data that the operation can be performed on (e.g. a group of contacts) + * - and a Role that has permission to do this operation. * + * Creating a new ACL requires at minimum a entity table, entity ID and object_table. + * + * @see https://docs.civicrm.org/user/en/latest/initial-set-up/permissions-and-access-control * @package Civi\Api4 */ class ACL extends Generic\DAOEntity { diff --git a/Civi/Api4/Action/Entity/Get.php b/Civi/Api4/Action/Entity/Get.php index bf7fd148c6..0e7d5e548f 100644 --- a/Civi/Api4/Action/Entity/Get.php +++ b/Civi/Api4/Action/Entity/Get.php @@ -59,7 +59,7 @@ class Get extends \Civi\Api4\Generic\BasicGetAction { && is_a('\Civi\Api4\\' . $matches[1], '\Civi\Api4\Generic\AbstractEntity', TRUE) ) { $entity = ['name' => $matches[1]]; - if ($this->_isFieldSelected('description') || $this->_isFieldSelected('comment')) { + if ($this->_isFieldSelected('description') || $this->_isFieldSelected('comment') || $this->_isFieldSelected('see')) { $this->addDocs($entity); } $entities[$matches[1]] = $entity; @@ -95,6 +95,10 @@ class Get extends \Civi\Api4\Generic\BasicGetAction { $entities[$fieldName] = [ 'name' => $fieldName, 'description' => $customEntity['title'] . ' custom group - extends ' . $customEntity['extends'], + 'see' => [ + 'https://docs.civicrm.org/user/en/latest/organising-your-data/creating-custom-fields/#multiple-record-fieldsets', + '\\Civi\\Api4\\CustomGroup', + ], ]; if (!empty($customEntity['help_pre'])) { $entities[$fieldName]['comment'] = $this->plainTextify($customEntity['help_pre']); diff --git a/Civi/Api4/ActionSchedule.php b/Civi/Api4/ActionSchedule.php index e3539dc922..7ddcb4ea65 100644 --- a/Civi/Api4/ActionSchedule.php +++ b/Civi/Api4/ActionSchedule.php @@ -30,6 +30,7 @@ namespace Civi\Api4; * * Creating a new ActionSchedule requires at minimum a title, mapping_id and entity_value. * + * @see https://docs.civicrm.org/user/en/latest/email/scheduled-reminders/ * @package Civi\Api4 */ class ActionSchedule extends Generic\DAOEntity { diff --git a/Civi/Api4/Activity.php b/Civi/Api4/Activity.php index 8761cd3d5b..c546502fc1 100644 --- a/Civi/Api4/Activity.php +++ b/Civi/Api4/Activity.php @@ -32,6 +32,7 @@ namespace Civi\Api4; * * An activity is a record of some type of interaction with one or more contacts. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/activities/ * @package Civi\Api4 */ class Activity extends Generic\DAOEntity { diff --git a/Civi/Api4/ActivityContact.php b/Civi/Api4/ActivityContact.php index 237c62e8fb..24dbc69423 100644 --- a/Civi/Api4/ActivityContact.php +++ b/Civi/Api4/ActivityContact.php @@ -28,6 +28,7 @@ namespace Civi\Api4; * * Creating a new ActivityContact requires at minimum a contact_id and activity_id. * + * @see \Civi\Api4\Activity * @package Civi\Api4 */ class ActivityContact extends Generic\DAOEntity { diff --git a/Civi/Api4/Campaign.php b/Civi/Api4/Campaign.php index 361ae34c3e..719a625e4d 100644 --- a/Civi/Api4/Campaign.php +++ b/Civi/Api4/Campaign.php @@ -24,6 +24,7 @@ namespace Civi\Api4; /** * Campaign entity. * + * @see https://docs.civicrm.org/user/en/latest/campaign/what-is-civicampaign/ * @package Civi\Api4 */ class Campaign extends Generic\DAOEntity { diff --git a/Civi/Api4/Contact.php b/Civi/Api4/Contact.php index d0257579db..7a5e600ccd 100644 --- a/Civi/Api4/Contact.php +++ b/Civi/Api4/Contact.php @@ -29,6 +29,7 @@ namespace Civi\Api4; * * Creating a new contact requires at minimum a name or email address. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/contacts/ * @package Civi\Api4 */ class Contact extends Generic\DAOEntity { diff --git a/Civi/Api4/ContactType.php b/Civi/Api4/ContactType.php index 98822f11c6..8cf2d9a134 100644 --- a/Civi/Api4/ContactType.php +++ b/Civi/Api4/ContactType.php @@ -30,6 +30,8 @@ namespace Civi\Api4; * * Creating a new contact type requires at minimum a label and parent_id. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/contacts/#contact-subtypes + * @see \Civi\Api4\Contact * @package Civi\Api4 */ class ContactType extends Generic\DAOEntity { diff --git a/Civi/Api4/CustomField.php b/Civi/Api4/CustomField.php index 702a5dc3e9..7cee0b982b 100644 --- a/Civi/Api4/CustomField.php +++ b/Civi/Api4/CustomField.php @@ -24,6 +24,8 @@ namespace Civi\Api4; /** * CustomField entity. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/creating-custom-fields/ + * * @package Civi\Api4 */ class CustomField extends Generic\DAOEntity { diff --git a/Civi/Api4/CustomGroup.php b/Civi/Api4/CustomGroup.php index 76ca7c6f39..47c6ca05fc 100644 --- a/Civi/Api4/CustomGroup.php +++ b/Civi/Api4/CustomGroup.php @@ -24,6 +24,8 @@ namespace Civi\Api4; /** * CustomGroup entity. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/creating-custom-fields/ + * * @package Civi\Api4 */ class CustomGroup extends Generic\DAOEntity { diff --git a/Civi/Api4/Domain.php b/Civi/Api4/Domain.php index 01172433b6..589f57052e 100644 --- a/Civi/Api4/Domain.php +++ b/Civi/Api4/Domain.php @@ -24,6 +24,8 @@ namespace Civi\Api4; /** * Domains - multisite instances of CiviCRM. * + * @see https://docs.civicrm.org/sysadmin/en/latest/setup/multisite/ + * * @package Civi\Api4 */ class Domain extends Generic\DAOEntity { diff --git a/Civi/Api4/Entity.php b/Civi/Api4/Entity.php index 090550184e..502de6a39b 100644 --- a/Civi/Api4/Entity.php +++ b/Civi/Api4/Entity.php @@ -24,6 +24,8 @@ namespace Civi\Api4; /** * Retrieves information about all Api4 entities. * + * @see \Civi\Api4\Generic\AbstractEntity + * * @package Civi\Api4 */ class Entity extends Generic\AbstractEntity { diff --git a/Civi/Api4/EntityTag.php b/Civi/Api4/EntityTag.php index 7760c1854d..06ae229c19 100644 --- a/Civi/Api4/EntityTag.php +++ b/Civi/Api4/EntityTag.php @@ -18,12 +18,13 @@ * */ - namespace Civi\Api4; /** * EntityTag - links tags to contacts, activities, etc. * + * @see \Civi\Api4\Tag + * * @package Civi\Api4 */ class EntityTag extends Generic\DAOEntity { diff --git a/Civi/Api4/Event.php b/Civi/Api4/Event.php index 09f19fd13a..c21a0def34 100644 --- a/Civi/Api4/Event.php +++ b/Civi/Api4/Event.php @@ -24,6 +24,8 @@ namespace Civi\Api4; /** * Event entity. * + * @see https://docs.civicrm.org/user/en/latest/events/what-is-civievent/ + * * @package Civi\Api4 */ class Event extends Generic\DAOEntity { diff --git a/Civi/Api4/Event/Events.php b/Civi/Api4/Event/Events.php index 9586b10181..bb866e287b 100644 --- a/Civi/Api4/Event/Events.php +++ b/Civi/Api4/Event/Events.php @@ -27,7 +27,7 @@ class Events { * Prepare the specification for a request. Fired from within a request to * get fields. * - * @see GetSpecEvent + * @see \Civi\Api4\Event\GetSpecEvent */ const GET_SPEC = 'civi.api.get_spec'; diff --git a/Civi/Api4/Group.php b/Civi/Api4/Group.php index 334e62d17e..b1cfa8591a 100644 --- a/Civi/Api4/Group.php +++ b/Civi/Api4/Group.php @@ -18,12 +18,13 @@ * */ - namespace Civi\Api4; /** * Group entity. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/groups-and-tags/#groups + * * @package Civi\Api4 */ class Group extends Generic\DAOEntity { diff --git a/Civi/Api4/GroupContact.php b/Civi/Api4/GroupContact.php index 7af2722431..62d1b2dc0f 100644 --- a/Civi/Api4/GroupContact.php +++ b/Civi/Api4/GroupContact.php @@ -18,7 +18,6 @@ * */ - namespace Civi\Api4; /** @@ -27,6 +26,8 @@ namespace Civi\Api4; * A contact can either be "Added" "Removed" or "Pending" in a group. * CiviCRM only considers them to be "in" a group if their status is "Added". * + * @see \Civi\Api4\Group + * * @package Civi\Api4 */ class GroupContact extends Generic\DAOEntity { diff --git a/Civi/Api4/GroupNesting.php b/Civi/Api4/GroupNesting.php index 83e4ad77d7..96276beee6 100644 --- a/Civi/Api4/GroupNesting.php +++ b/Civi/Api4/GroupNesting.php @@ -23,6 +23,8 @@ namespace Civi\Api4; /** * GroupNesting entity. * + * @see \Civi\Api4\Group + * * @package Civi\Api4 */ class GroupNesting extends Generic\DAOEntity { diff --git a/Civi/Api4/GroupOrganization.php b/Civi/Api4/GroupOrganization.php index a640e2cb93..e98654dcf4 100644 --- a/Civi/Api4/GroupOrganization.php +++ b/Civi/Api4/GroupOrganization.php @@ -23,6 +23,9 @@ namespace Civi\Api4; /** * GroupOrganization entity. * + * Relates groups to organizations. + * + * @see \Civi\Api4\Group * @package Civi\Api4 */ class GroupOrganization extends Generic\DAOEntity { diff --git a/Civi/Api4/Mapping.php b/Civi/Api4/Mapping.php index 341cf1698f..c54f0dd534 100644 --- a/Civi/Api4/Mapping.php +++ b/Civi/Api4/Mapping.php @@ -18,7 +18,6 @@ * */ - namespace Civi\Api4; /** diff --git a/Civi/Api4/MappingField.php b/Civi/Api4/MappingField.php index e59be2b131..16cf57ad56 100644 --- a/Civi/Api4/MappingField.php +++ b/Civi/Api4/MappingField.php @@ -18,7 +18,6 @@ * */ - namespace Civi\Api4; /** @@ -26,6 +25,8 @@ namespace Civi\Api4; * * This represents one field in a Mapping collection. * + * @see \Civi\Api4\Mapping + * * @package Civi\Api4 */ class MappingField extends Generic\DAOEntity { diff --git a/Civi/Api4/Navigation.php b/Civi/Api4/Navigation.php index 440a4818df..9833842ec7 100644 --- a/Civi/Api4/Navigation.php +++ b/Civi/Api4/Navigation.php @@ -18,7 +18,6 @@ * */ - namespace Civi\Api4; /** diff --git a/Civi/Api4/OptionGroup.php b/Civi/Api4/OptionGroup.php index 751334945c..22f28d5fcf 100644 --- a/Civi/Api4/OptionGroup.php +++ b/Civi/Api4/OptionGroup.php @@ -24,6 +24,7 @@ namespace Civi\Api4; /** * OptionGroup entity. * + * @see \Civi\Api4\OptionValue * @package Civi\Api4 */ class OptionGroup extends Generic\DAOEntity { diff --git a/Civi/Api4/OptionValue.php b/Civi/Api4/OptionValue.php index 8d8946d2eb..98e9cae388 100644 --- a/Civi/Api4/OptionValue.php +++ b/Civi/Api4/OptionValue.php @@ -24,6 +24,7 @@ namespace Civi\Api4; /** * OptionValue entity. * + * @see \Civi\Api4\OptionGroup * @package Civi\Api4 */ class OptionValue extends Generic\DAOEntity { diff --git a/Civi/Api4/Participant.php b/Civi/Api4/Participant.php index a5c4115f61..473deace0c 100644 --- a/Civi/Api4/Participant.php +++ b/Civi/Api4/Participant.php @@ -18,7 +18,6 @@ * */ - namespace Civi\Api4; /** diff --git a/Civi/Api4/PaymentProcessor.php b/Civi/Api4/PaymentProcessor.php index 5cf857c74d..c15a448733 100644 --- a/Civi/Api4/PaymentProcessor.php +++ b/Civi/Api4/PaymentProcessor.php @@ -20,6 +20,8 @@ namespace Civi\Api4; /** * Payment Processor entity. * + * @see https://docs.civicrm.org/sysadmin/en/latest/setup/payment-processors/ + * * @package Civi\Api4 */ class PaymentProcessor extends Generic\DAOEntity { diff --git a/Civi/Api4/PaymentProcessorType.php b/Civi/Api4/PaymentProcessorType.php index 94b94516f9..425d4ba122 100644 --- a/Civi/Api4/PaymentProcessorType.php +++ b/Civi/Api4/PaymentProcessorType.php @@ -20,6 +20,8 @@ namespace Civi\Api4; /** * Payment Processor Type entity. * + * @see \Civi\Api4\PaymentProcessor + * * @package Civi\Api4 */ class PaymentProcessorType extends Generic\DAOEntity { diff --git a/Civi/Api4/Provider/ActionObjectProvider.php b/Civi/Api4/Provider/ActionObjectProvider.php index 2180672cb0..b31c3d323f 100644 --- a/Civi/Api4/Provider/ActionObjectProvider.php +++ b/Civi/Api4/Provider/ActionObjectProvider.php @@ -61,7 +61,7 @@ class ActionObjectProvider implements EventSubscriberInterface, ProviderInterfac // Load result class based on @return annotation in the execute() method. $reflection = new \ReflectionClass($action); $doc = ReflectionUtils::getCodeDocs($reflection->getMethod('execute'), 'Method'); - $resultClass = \CRM_Utils_Array::value('return', $doc, '\\Civi\\Api4\\Generic\\Result'); + $resultClass = $doc['return'][0] ?? '\\Civi\\Api4\\Generic\\Result'; $result = new $resultClass(); $result->action = $action->getActionName(); $result->entity = $action->getEntityName(); diff --git a/Civi/Api4/Relationship.php b/Civi/Api4/Relationship.php index b7e26270c4..d1a76fede9 100644 --- a/Civi/Api4/Relationship.php +++ b/Civi/Api4/Relationship.php @@ -24,6 +24,8 @@ namespace Civi\Api4; /** * Relationship entity. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/relationships/ + * * @package Civi\Api4 */ class Relationship extends Generic\DAOEntity { diff --git a/Civi/Api4/RelationshipType.php b/Civi/Api4/RelationshipType.php index ea874c4452..59a10a6c37 100644 --- a/Civi/Api4/RelationshipType.php +++ b/Civi/Api4/RelationshipType.php @@ -24,6 +24,8 @@ namespace Civi\Api4; /** * RelationshipType entity. * + * @see \Civi\Api4\Relationship + * * @package Civi\Api4 */ class RelationshipType extends Generic\DAOEntity { diff --git a/Civi/Api4/Route.php b/Civi/Api4/Route.php index e1c5b779c5..f3d36bc61c 100644 --- a/Civi/Api4/Route.php +++ b/Civi/Api4/Route.php @@ -22,6 +22,17 @@ namespace Civi\Api4; use Civi\Api4\Generic\BasicGetFieldsAction; +/** + * CiviCRM menu route. + * + * Provides page routes registered in the CiviCRM menu system. + * + * Note: this is a read-only api as routes are set via xml files and hooks. + * + * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_alterMenu/ + * + * @package Civi\Api4 + */ class Route extends \Civi\Api4\Generic\AbstractEntity { /** diff --git a/Civi/Api4/Service/Spec/SpecGatherer.php b/Civi/Api4/Service/Spec/SpecGatherer.php index 0edb4e8c6a..dc7304731c 100644 --- a/Civi/Api4/Service/Spec/SpecGatherer.php +++ b/Civi/Api4/Service/Spec/SpecGatherer.php @@ -42,7 +42,7 @@ class SpecGatherer { /** * Returns a RequestSpec with all the fields available. Uses spec providers * to add or modify field specifications. - * For an example @see CustomFieldSpecProvider. + * @see \Civi\Api4\Service\Spec\Provider\CustomFieldCreationSpecProvider * * @param string $entity * @param string $action diff --git a/Civi/Api4/Setting.php b/Civi/Api4/Setting.php index cded4ed519..8b269fe214 100644 --- a/Civi/Api4/Setting.php +++ b/Civi/Api4/Setting.php @@ -26,6 +26,7 @@ namespace Civi\Api4; * * Used to read/write persistent setting data from CiviCRM. * + * @see \Civi\Core\SettingsBag * @package Civi\Api4 */ class Setting extends Generic\AbstractEntity { diff --git a/Civi/Api4/StatusPreference.php b/Civi/Api4/StatusPreference.php index d7318a5c90..0b106b2ae7 100644 --- a/Civi/Api4/StatusPreference.php +++ b/Civi/Api4/StatusPreference.php @@ -22,6 +22,8 @@ namespace Civi\Api4; /** + * StatusPreference entity. + * * For setting "hush" preferences for system check alerts. * * @package Civi\Api4 diff --git a/Civi/Api4/Tag.php b/Civi/Api4/Tag.php index 9d03a7f8bd..2aae3769ea 100644 --- a/Civi/Api4/Tag.php +++ b/Civi/Api4/Tag.php @@ -27,6 +27,7 @@ namespace Civi\Api4; * Tags in CiviCRM are used for Contacts, Activities, Cases & Attachments. * They are connected to those entities via the EntityTag table. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/groups-and-tags/#tags * @package Civi\Api4 */ class Tag extends Generic\DAOEntity { diff --git a/Civi/Api4/UFField.php b/Civi/Api4/UFField.php index df6970c9e8..3cb294f98f 100644 --- a/Civi/Api4/UFField.php +++ b/Civi/Api4/UFField.php @@ -24,6 +24,7 @@ namespace Civi\Api4; /** * UFField entity - aka profile fields. * + * @see \Civi\Api4\UFGroup * @package Civi\Api4 */ class UFField extends Generic\DAOEntity { diff --git a/Civi/Api4/UFGroup.php b/Civi/Api4/UFGroup.php index 890f34f311..dbf4b28820 100644 --- a/Civi/Api4/UFGroup.php +++ b/Civi/Api4/UFGroup.php @@ -24,6 +24,7 @@ namespace Civi\Api4; /** * UFGroup entity - AKA profiles. * + * @see https://docs.civicrm.org/user/en/latest/organising-your-data/profiles/ * @package Civi\Api4 */ class UFGroup extends Generic\DAOEntity { diff --git a/Civi/Api4/UFJoin.php b/Civi/Api4/UFJoin.php index 995e34f5a5..6112ee1c1d 100644 --- a/Civi/Api4/UFJoin.php +++ b/Civi/Api4/UFJoin.php @@ -24,6 +24,7 @@ namespace Civi\Api4; /** * UFJoin entity - links profiles to the components/extensions they are used for. * + * @see \Civi\Api4\UFGroup * @package Civi\Api4 */ class UFJoin extends Generic\DAOEntity { diff --git a/Civi/Api4/Utils/ReflectionUtils.php b/Civi/Api4/Utils/ReflectionUtils.php index 58b3aab951..a0d4b799f3 100644 --- a/Civi/Api4/Utils/ReflectionUtils.php +++ b/Civi/Api4/Utils/ReflectionUtils.php @@ -76,11 +76,14 @@ class ReflectionUtils { if ($key == 'var') { $info['type'] = explode('|', $words[0]); } + elseif ($key == 'return') { + $info['return'] = explode('|', $words[0]); + } elseif ($key == 'options') { $val = str_replace(', ', ',', implode(' ', $words)); $info['options'] = explode(',', $val); } - elseif ($key == 'throws') { + elseif ($key == 'throws' || $key == 'see') { $info[$key][] = implode(' ', $words); } elseif ($key == 'param' && $words) { diff --git a/ang/api4Explorer/Explorer.html b/ang/api4Explorer/Explorer.html index bd4b09636a..4a3da7b4d6 100644 --- a/ang/api4Explorer/Explorer.html +++ b/ang/api4Explorer/Explorer.html @@ -121,9 +121,17 @@ -

+

{{ key }}: {{ item }}

+
+ See: + +
diff --git a/ang/api4Explorer/Explorer.js b/ang/api4Explorer/Explorer.js index 10a78d5ae6..3c5c5ca0b9 100644 --- a/ang/api4Explorer/Explorer.js +++ b/ang/api4Explorer/Explorer.js @@ -146,6 +146,18 @@ } }; + // 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) { @@ -565,13 +577,14 @@ $scope.helpTitle = helpTitle = $scope.entity; $scope.helpContent = helpContent = { description: entityInfo.description, - comment: entityInfo.comment + comment: entityInfo.comment, + see: entityInfo.see }; } if (!$scope.entity) { $scope.helpTitle = helpTitle = ts('APIv4 Explorer'); - $scope.helpContent = helpContent = {description: docs.description, comment: docs.comment}; + $scope.helpContent = helpContent = {description: docs.description, comment: docs.comment, see: docs.see}; } else if (!actions.length && !getEntity().actions) { getMetaParams.actions = [$scope.entity, 'getActions', {chain: {fields: [$scope.entity, 'getFields', {action: '$name'}]}}]; fetchMeta(); @@ -598,7 +611,7 @@ $location.url('/explorer/' + $scope.entity + '/' + newVal); } else if (newVal) { $scope.helpTitle = helpTitle = $scope.entity + '::' + newVal; - $scope.helpContent = helpContent = _.pick(_.findWhere(getEntity().actions, {name: newVal}), ['description', 'comment']); + $scope.helpContent = helpContent = _.pick(_.findWhere(getEntity().actions, {name: newVal}), ['description', 'comment', 'see']); } }); diff --git a/api/api.php b/api/api.php index c5cae1e27f..224846279f 100644 --- a/api/api.php +++ b/api/api.php @@ -24,13 +24,13 @@ function civicrm_api(string $entity = NULL, string $action, array $params, $extr } /** - * Calls the CiviCRM APIv4 with supplied parameters and returns a Result object. + * CiviCRM API version 4. * * This API (Application Programming Interface) is used to access and manage data in CiviCRM. * * APIv4 is the latest stable version. * - * @see http://example.com/civicrm/api4/explorer + * @see https://docs.civicrm.org/dev/en/latest/api/v4/usage/ * * @param string $entity Name of the CiviCRM entity to access. * All entity names are capitalized CamelCase, e.g. "ContributionPage". diff --git a/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php b/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php index 8323318041..8e02868a53 100644 --- a/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php +++ b/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php @@ -70,12 +70,13 @@ This is the base class.'; * * Comment. * IDK + * @see 0 * @param int|string \$foo * Nothing interesting. - * @see 0 + * @see no evil * @throws tantrums * @param \$bar: - Has a title - * @return nothing + * @return nothing|something */ ", [ @@ -93,9 +94,9 @@ This is the base class.'; 'comment' => '', ], ], - 'see' => '0', + 'see' => ['0', 'no evil'], 'throws' => ['tantrums'], - 'return' => 'nothing', + 'return' => ['nothing', 'something'], ], ], ]; -- 2.25.1