From ea26062189f9ebc4005782688e4e82e9736e23d6 Mon Sep 17 00:00:00 2001
From: colemanw <coleman@civicrm.org>
Date: Mon, 2 Oct 2023 18:10:41 -0400
Subject: [PATCH] APIv4 - add docs about Individual, Household, Organization
 apis

---
 Civi/Api4/Contact.php      | 4 +++-
 Civi/Api4/Household.php    | 6 ++++++
 Civi/Api4/Individual.php   | 6 ++++++
 Civi/Api4/Organization.php | 6 ++++++
 4 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/Civi/Api4/Contact.php b/Civi/Api4/Contact.php
index 2645674fef..c71aabd357 100644
--- a/Civi/Api4/Contact.php
+++ b/Civi/Api4/Contact.php
@@ -113,8 +113,10 @@ class Contact extends Generic\DAOEntity {
     $contactType = static::getEntityName();
     // Adjust info for child classes (Individual, Organization, Household)
     if ($contactType !== 'Contact') {
-      $info['icon'] = \CRM_Contact_BAO_ContactType::getContactType($contactType)['icon'] ?? $info['icon'];
+      $contactTypeInfo = \CRM_Contact_BAO_ContactType::getContactType($contactType);
+      $info['icon'] = $contactTypeInfo['icon'] ?? $info['icon'];
       $info['type'] = ['DAOEntity', 'ContactType'];
+      $info['description'] = ts('Contacts of type %1.', [1 => $contactTypeInfo['label']]);
       // This forces the value into get and create api actions
       $info['where'] = ['contact_type' => $contactType];
     }
diff --git a/Civi/Api4/Household.php b/Civi/Api4/Household.php
index 10fd4acb60..3807d0c289 100644
--- a/Civi/Api4/Household.php
+++ b/Civi/Api4/Household.php
@@ -13,6 +13,12 @@ namespace Civi\Api4;
 /**
  * Contacts of type Household.
  *
+ * This api is a facade for the Contact entity.
+ * In most ways it acts exactly like the Contact entity, but will inject [contact_type => Individual]
+ * into get, create, and batch actions (however, when updating or deleting a single Contact by id,
+ * this will transparently pass-through to the Contact entity, so don't rely on this facade to enforce
+ * contact type for single-record-by-id write operations).
+ *
  * @inheritDoc
  * @searchable secondary
  * @since 5.67
diff --git a/Civi/Api4/Individual.php b/Civi/Api4/Individual.php
index 222491978d..f72f8cde87 100644
--- a/Civi/Api4/Individual.php
+++ b/Civi/Api4/Individual.php
@@ -13,6 +13,12 @@ namespace Civi\Api4;
 /**
  * Contacts of type Individual.
  *
+ * This api is a facade for the Contact entity.
+ * In most ways it acts exactly like the Contact entity, but will inject [contact_type => Individual]
+ * into get, create, and batch actions (however, when updating or deleting a single Contact by id,
+ * this will transparently pass-through to the Contact entity, so don't rely on this facade to enforce
+ * contact type for single-record-by-id write operations).
+ *
  * @inheritDoc
  * @since 5.67
  * @package Civi\Api4
diff --git a/Civi/Api4/Organization.php b/Civi/Api4/Organization.php
index b14d72cc43..6b1e9a06ce 100644
--- a/Civi/Api4/Organization.php
+++ b/Civi/Api4/Organization.php
@@ -13,6 +13,12 @@ namespace Civi\Api4;
 /**
  * Contacts of type Organization.
  *
+ * This api is a facade for the Contact entity.
+ * In most ways it acts exactly like the Contact entity, but will inject [contact_type => Organization]
+ * into get, create, and batch actions (however, when updating or deleting a single Contact by id,
+ * this will transparently pass-through to the Contact entity, so don't rely on this facade to enforce
+ * contact type for single-record-by-id write operations).
+ *
  * @inheritDoc
  * @since 5.67
  * @package Civi\Api4
-- 
2.25.1