Api4 - Improve docblocks and their display in the Explorer

diff --git a/Civi/Api4/Action/Contact/GetFields.php b/Civi/Api4/Action/Contact/GetFields.php
index 041b91d291176f5b36e5494671101e7e05896d53..da6fc33409f440392d68714e6b5e96f6c59f5e97 100644 (file)
--- a/Civi/Api4/Action/Contact/GetFields.php
+++ b/Civi/Api4/Action/Contact/GetFields.php
@@ -22,6 +22,9 @@ namespace Civi\Api4\Action\Contact;
 
 use Civi\Api4\Generic\DAOGetFieldsAction;
 
+/**
+ * @inheritDoc
+ */
 class GetFields extends DAOGetFieldsAction {
 
   protected function getRecords() {

diff --git a/Civi/Api4/Action/GetActions.php b/Civi/Api4/Action/GetActions.php
index 2a022206b16deaa6bca9dcb84f9282650db81dcb..46dae610314aaeb00ad368b74a7e7fd039b07c4b 100644 (file)
--- a/Civi/Api4/Action/GetActions.php
+++ b/Civi/Api4/Action/GetActions.php
@@ -42,7 +42,7 @@ class GetActions extends BasicGetAction {
     foreach ($entityReflection->getMethods(\ReflectionMethod::IS_STATIC | \ReflectionMethod::IS_PUBLIC) as $method) {
       $actionName = $method->getName();
       if ($actionName != 'permissions' && $actionName[0] != '_') {
-        $this->loadAction($actionName);
+        $this->loadAction($actionName, $method);
       }
     }
     if (!$this->_actionsToGet || count($this->_actionsToGet) > count($this->_actions)) {
@@ -77,18 +77,24 @@ class GetActions extends BasicGetAction {
 
   /**
    * @param $actionName
+   * @param \ReflectionMethod $method
    */
-  private function loadAction($actionName) {
+  private function loadAction($actionName, $method = NULL) {
     try {
       if (!isset($this->_actions[$actionName]) && (!$this->_actionsToGet || in_array($actionName, $this->_actionsToGet))) {
         $action = ActionUtil::getAction($this->getEntityName(), $actionName);
         if (is_object($action)) {
           $this->_actions[$actionName] = ['name' => $actionName];
-          if ($this->_isFieldSelected('description', 'comment')) {
-            $actionReflection = new \ReflectionClass($action);
-            $actionInfo = ReflectionUtils::getCodeDocs($actionReflection);
-            unset($actionInfo['method']);
-            $this->_actions[$actionName] += $actionInfo;
+          if ($this->_isFieldSelected('description', 'comment', 'see')) {
+            // Docblock from action class
+            $actionDocs = ReflectionUtils::getCodeDocs($action->reflect());
+            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;
+            }
+            $this->_actions[$actionName] += $actionDocs;
           }
           if ($this->_isFieldSelected('params')) {
             $this->_actions[$actionName]['params'] = $action->getParamInfo();
@@ -112,18 +118,24 @@ class GetActions extends BasicGetAction {
     return [
       [
         'name' => 'name',
-        'data_type' => 'String',
+        'description' => 'Action name',
       ],
       [
         'name' => 'description',
-        'data_type' => 'String',
+        'description' => 'Description from docblock',
       ],
       [
         'name' => 'comment',
-        'data_type' => 'String',
+        'description' => 'Comments from docblock',
+      ],
+      [
+        'name' => 'see',
+        'data_type' => 'Array',
+        'description' => 'Any @see annotations from docblock',
       ],
       [
         'name' => 'params',
+        'description' => 'List of all accepted parameters',
         'data_type' => 'Array',
       ],
     ];

diff --git a/Civi/Api4/Contact.php b/Civi/Api4/Contact.php
index 7a5e600ccd31db941ff2874df92d27fc69210491..ca650abc7b8c356b572ffa626539ecb084ff6db8 100644 (file)
--- a/Civi/Api4/Contact.php
+++ b/Civi/Api4/Contact.php
@@ -34,14 +34,23 @@ namespace Civi\Api4;
  */
 class Contact extends Generic\DAOEntity {
 
+  /**
+   * @return \Civi\Api4\Action\Contact\GetFields|Generic\DAOGetFieldsAction
+   */
   public static function getFields() {
     return new Action\Contact\GetFields(__CLASS__, __FUNCTION__);
   }
 
+  /**
+   * @return \Civi\Api4\Action\Contact\GetChecksum
+   */
   public static function getChecksum() {
     return new Action\Contact\GetChecksum(__CLASS__, __FUNCTION__);
   }
 
+  /**
+   * @return \Civi\Api4\Action\Contact\ValidateChecksum
+   */
   public static function validateChecksum() {
     return new Action\Contact\ValidateChecksum(__CLASS__, __FUNCTION__);
   }

diff --git a/Civi/Api4/Entity.php b/Civi/Api4/Entity.php
index ac45fef8638d8e0cc56b7738162c795926609b28..430900b663737fbe88f29eb58fc57ea89c9b479d 100644 (file)
--- a/Civi/Api4/Entity.php
+++ b/Civi/Api4/Entity.php
@@ -57,7 +57,7 @@ class Entity extends Generic\AbstractEntity {
         ],
         [
           'name' => 'see',
-          'type' => 'Array',
+          'data_type' => 'Array',
           'description' => 'Any @see annotations from docblock',
         ],
       ];

diff --git a/Civi/Api4/Event/Subscriber/PostSelectQuerySubscriber.php b/Civi/Api4/Event/Subscriber/PostSelectQuerySubscriber.php
index 7add31036bcd06c5eb68d72e89421b75d3a8ce4a..44476c5916e3c5d597067a0871adda749f83f9c2 100644 (file)
--- a/Civi/Api4/Event/Subscriber/PostSelectQuerySubscriber.php
+++ b/Civi/Api4/Event/Subscriber/PostSelectQuerySubscriber.php
@@ -34,7 +34,7 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 class PostSelectQuerySubscriber implements EventSubscriberInterface {
 
   /**
-   * @inheritdoc
+   * @inheritDoc
    */
   public static function getSubscribedEvents() {
     return [

diff --git a/Civi/Api4/Generic/BasicGetFieldsAction.php b/Civi/Api4/Generic/BasicGetFieldsAction.php
index 6bf10788162736bc07fe131247ae679f67615198..19f548e6a06a3b97b8ec889aaaeab1caf374307e 100644 (file)
--- a/Civi/Api4/Generic/BasicGetFieldsAction.php
+++ b/Civi/Api4/Generic/BasicGetFieldsAction.php
@@ -25,7 +25,13 @@ use Civi\API\Exception\NotImplementedException;
 use Civi\Api4\Utils\ActionUtil;
 
 /**
- * Get fields for an entity.
+ * Get information about an entity's fields.
+ *
+ * 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,
+ * but a different list may be returned if you specify another action.
  *
  * @method $this setLoadOptions(bool $value)
  * @method bool getLoadOptions()

diff --git a/Civi/Api4/Generic/DAOGetFieldsAction.php b/Civi/Api4/Generic/DAOGetFieldsAction.php
index d64155fd0b672222676c426a58d008b50e9f87a6..992eca6707c8aced4b25ad808bcfb52be657b92b 100644 (file)
--- a/Civi/Api4/Generic/DAOGetFieldsAction.php
+++ b/Civi/Api4/Generic/DAOGetFieldsAction.php
@@ -24,8 +24,7 @@ namespace Civi\Api4\Generic;
 use Civi\Api4\Service\Spec\SpecFormatter;
 
 /**
- * Get fields for a DAO-based entity.
- *
+ * @inheritDoc
  * @method $this setIncludeCustom(bool $value)
  * @method bool getIncludeCustom()
  */
@@ -39,7 +38,7 @@ class DAOGetFieldsAction extends BasicGetFieldsAction {
   protected $includeCustom = TRUE;
 
   /**
-   * Get fields for a DAO-based entity
+   * Get fields for a DAO-based entity.
    *
    * @return array
    */