Api4 - improve docblocks & display links in explorer

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 {

Civi/Api4/Action/Entity/Get.php

@@ -59,7 +59,7 @@ protected function getRecords() {
             && 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 @@ private function addCustomEntities(&$entities) {
       $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']);

Civi/Api4/ActionSchedule.php

@@ -30,6 +30,7 @@
  *
  * 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 {

Civi/Api4/Activity.php

@@ -32,6 +32,7 @@
  *
  * 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 {

Civi/Api4/ActivityContact.php

@@ -28,6 +28,7 @@
  *
  * 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 {

Civi/Api4/Campaign.php

@@ -24,6 +24,7 @@
 /**
  * Campaign entity.
  *
+ * @see https://docs.civicrm.org/user/en/latest/campaign/what-is-civicampaign/
  * @package Civi\Api4
  */
 class Campaign extends Generic\DAOEntity {

Civi/Api4/Contact.php

@@ -29,6 +29,7 @@
  *
  * 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 {

Civi/Api4/ContactType.php

@@ -30,6 +30,8 @@
  *
  * 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 {

Civi/Api4/CustomField.php

@@ -24,6 +24,8 @@
 /**
  * CustomField entity.
  *
+ * @see https://docs.civicrm.org/user/en/latest/organising-your-data/creating-custom-fields/
+ *
  * @package Civi\Api4
  */
 class CustomField extends Generic\DAOEntity {

Civi/Api4/CustomGroup.php

@@ -24,6 +24,8 @@
 /**
  * CustomGroup entity.
  *
+ * @see https://docs.civicrm.org/user/en/latest/organising-your-data/creating-custom-fields/
+ *
  * @package Civi\Api4
  */
 class CustomGroup extends Generic\DAOEntity {

Civi/Api4/Domain.php

@@ -24,6 +24,8 @@
 /**
  * Domains - multisite instances of CiviCRM.
  *
+ * @see https://docs.civicrm.org/sysadmin/en/latest/setup/multisite/
+ *
  * @package Civi\Api4
  */
 class Domain extends Generic\DAOEntity {

Civi/Api4/Entity.php

@@ -24,6 +24,8 @@
 /**
  * Retrieves information about all Api4 entities.
  *
+ * @see \Civi\Api4\Generic\AbstractEntity
+ *
  * @package Civi\Api4
  */
 class Entity extends Generic\AbstractEntity {

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 {

Civi/Api4/Event.php

@@ -24,6 +24,8 @@
 /**
  * Event entity.
  *
+ * @see https://docs.civicrm.org/user/en/latest/events/what-is-civievent/
+ *
  * @package Civi\Api4
  */
 class Event extends Generic\DAOEntity {

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';
 

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 {

Civi/Api4/GroupContact.php

@@ -18,7 +18,6 @@
  *
  */
 
-
 namespace Civi\Api4;
 
 /**
@@ -27,6 +26,8 @@
  * 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 {

Civi/Api4/GroupNesting.php

@@ -23,6 +23,8 @@
 /**
  * GroupNesting entity.
  *
+ * @see \Civi\Api4\Group
+ *
  * @package Civi\Api4
  */
 class GroupNesting extends Generic\DAOEntity {

Civi/Api4/GroupOrganization.php

@@ -23,6 +23,9 @@
 /**
  * GroupOrganization entity.
  *
+ * Relates groups to organizations.
+ *
+ * @see \Civi\Api4\Group
  * @package Civi\Api4
  */
 class GroupOrganization extends Generic\DAOEntity {

Civi/Api4/Mapping.php

@@ -18,7 +18,6 @@
  *
  */
 
-
 namespace Civi\Api4;
 
 /**

Civi/Api4/MappingField.php

@@ -18,14 +18,15 @@
  *
  */
 
-
 namespace Civi\Api4;
 
 /**
  * MappingField entity.
  *
  * This represents one field in a Mapping collection.
  *
+ * @see \Civi\Api4\Mapping
+ *
  * @package Civi\Api4
  */
 class MappingField extends Generic\DAOEntity {

Civi/Api4/Navigation.php

@@ -18,7 +18,6 @@
  *
  */
 
-
 namespace Civi\Api4;
 
 /**

Civi/Api4/OptionGroup.php

@@ -24,6 +24,7 @@
 /**
  * OptionGroup entity.
  *
+ * @see \Civi\Api4\OptionValue
  * @package Civi\Api4
  */
 class OptionGroup extends Generic\DAOEntity {

Civi/Api4/OptionValue.php

@@ -24,6 +24,7 @@
 /**
  * OptionValue entity.
  *
+ * @see \Civi\Api4\OptionGroup
  * @package Civi\Api4
  */
 class OptionValue extends Generic\DAOEntity {

Civi/Api4/Participant.php

@@ -18,7 +18,6 @@
  *
  */
 
-
 namespace Civi\Api4;
 
 /**

Civi/Api4/PaymentProcessor.php

@@ -20,6 +20,8 @@
 /**
  * Payment Processor entity.
  *
+ * @see https://docs.civicrm.org/sysadmin/en/latest/setup/payment-processors/
+ *
  * @package Civi\Api4
  */
 class PaymentProcessor extends Generic\DAOEntity {

Civi/Api4/PaymentProcessorType.php

@@ -20,6 +20,8 @@
 /**
  * Payment Processor Type entity.
  *
+ * @see \Civi\Api4\PaymentProcessor
+ *
  * @package Civi\Api4
  */
 class PaymentProcessorType extends Generic\DAOEntity {

Civi/Api4/Provider/ActionObjectProvider.php

@@ -61,7 +61,7 @@ public function invoke($action) {
     // 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();

Civi/Api4/Relationship.php

@@ -24,6 +24,8 @@
 /**
  * Relationship entity.
  *
+ * @see https://docs.civicrm.org/user/en/latest/organising-your-data/relationships/
+ *
  * @package Civi\Api4
  */
 class Relationship extends Generic\DAOEntity {

Civi/Api4/RelationshipType.php

@@ -24,6 +24,8 @@
 /**
  * RelationshipType entity.
  *
+ * @see \Civi\Api4\Relationship
+ *
  * @package Civi\Api4
  */
 class RelationshipType extends Generic\DAOEntity {

Civi/Api4/Route.php

@@ -22,6 +22,17 @@
 
 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 {
 
   /**

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

Civi/Api4/Setting.php

@@ -26,6 +26,7 @@
  *
  * Used to read/write persistent setting data from CiviCRM.
  *
+ * @see \Civi\Core\SettingsBag
  * @package Civi\Api4
  */
 class Setting extends Generic\AbstractEntity {

Civi/Api4/StatusPreference.php

@@ -22,6 +22,8 @@
 namespace Civi\Api4;
 
 /**
+ * StatusPreference entity.
+ *
  * For setting "hush" preferences for system check alerts.
  *
  * @package Civi\Api4

Civi/Api4/Tag.php

@@ -27,6 +27,7 @@
  * 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 {

Civi/Api4/UFField.php

@@ -24,6 +24,7 @@
 /**
  * UFField entity - aka profile fields.
  *
+ * @see \Civi\Api4\UFGroup
  * @package Civi\Api4
  */
 class UFField extends Generic\DAOEntity {

Civi/Api4/UFGroup.php

@@ -24,6 +24,7 @@
 /**
  * UFGroup entity - AKA profiles.
  *
+ * @see https://docs.civicrm.org/user/en/latest/organising-your-data/profiles/
  * @package Civi\Api4
  */
 class UFGroup extends Generic\DAOEntity {

Civi/Api4/UFJoin.php

@@ -24,6 +24,7 @@
 /**
  * UFJoin entity - links profiles to the components/extensions they are used for.
  *
+ * @see \Civi\Api4\UFGroup
  * @package Civi\Api4
  */
 class UFJoin extends Generic\DAOEntity {