From f827fe4954f0563545cd1d472ca84c580175c7d6 Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Sat, 25 Jan 2020 10:49:28 -0500
Subject: [PATCH] Improve code docs for Api4 Entity entity

---
 Civi/Api4/Action/Entity/Get.php |  6 +++++-
 Civi/Api4/Entity.php            | 20 +++++++++++++++++---
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/Civi/Api4/Action/Entity/Get.php b/Civi/Api4/Action/Entity/Get.php
index 15a53dab58..37e59f2edc 100644
--- a/Civi/Api4/Action/Entity/Get.php
+++ b/Civi/Api4/Action/Entity/Get.php
@@ -25,7 +25,11 @@ use Civi\Api4\CustomGroup;
 use Civi\Api4\Utils\ReflectionUtils;
 
 /**
- * Get entities
+ * Get the names & docblocks of all APIv4 entities.
+ *
+ * Scans for api entities in core + enabled extensions.
+ *
+ * Also includes pseudo-entities from multi-record custom groups by default.
  *
  * @method $this setIncludeCustom(bool $value)
  * @method bool getIncludeCustom()
diff --git a/Civi/Api4/Entity.php b/Civi/Api4/Entity.php
index 502de6a39b..ac45fef863 100644
--- a/Civi/Api4/Entity.php
+++ b/Civi/Api4/Entity.php
@@ -43,9 +43,23 @@ class Entity extends Generic\AbstractEntity {
   public static function getFields() {
     return new \Civi\Api4\Generic\BasicGetFieldsAction('Entity', __FUNCTION__, function() {
       return [
-        ['name' => 'name'],
-        ['name' => 'description'],
-        ['name' => 'comment'],
+        [
+          'name' => 'name',
+          'description' => 'Entity name',
+        ],
+        [
+          'name' => 'description',
+          'description' => 'Description from docblock',
+        ],
+        [
+          'name' => 'comment',
+          'description' => 'Comments from docblock',
+        ],
+        [
+          'name' => 'see',
+          'type' => 'Array',
+          'description' => 'Any @see annotations from docblock',
+        ],
       ];
     });
   }
-- 
2.25.1