From 1df69f8fb500e1517533db294342aaa81061e83a Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 28 Jun 2022 19:37:03 -0700
Subject: [PATCH] (NFC) Expand docblocks for hook_install and hook_postInstall

---
 CRM/Extension/Upgrader/Base.php | 20 ++++++++++++++++++++
 CRM/Utils/Hook.php              | 32 +++++++++++++++++++++++++++++---
 2 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/CRM/Extension/Upgrader/Base.php b/CRM/Extension/Upgrader/Base.php
index 3dbd1eb069..1478af7540 100644
--- a/CRM/Extension/Upgrader/Base.php
+++ b/CRM/Extension/Upgrader/Base.php
@@ -36,6 +36,16 @@ class CRM_Extension_Upgrader_Base implements CRM_Extension_Upgrader_Interface {
   // ******** Hook delegates ********
 
   /**
+   * Run early installation steps. Ex: Create new MySQL table.
+   *
+   * This dispatches directly to each new extension. You will only receive notices for your own installation.
+   *
+   * If multiple extensions are installed simultaneously, they will all run
+   * `hook_install`/`hook_enable` back-to-back (in order of dependency).
+   *
+   * This runs BEFORE refreshing major caches and services (such as
+   * `ManagedEntities` and `CRM_Logging_Schema`).
+   *
    * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_install
    */
   public function onInstall() {
@@ -63,6 +73,16 @@ class CRM_Extension_Upgrader_Base implements CRM_Extension_Upgrader_Interface {
   }
 
   /**
+   * Run later installation steps. Ex: Call a bespoke API-job for the first time.
+   *
+   * This dispatches directly to each new extension. You will only receive notices for your own installation.
+   *
+   * If multiple extensions are installed simultaneously, they will all run
+   * `hook_postInstall` back-to-back (in order of dependency).
+   *
+   * This runs AFTER refreshing major caches and services (such as
+   * `ManagedEntities` and `CRM_Logging_Schema`).
+   *
    * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_postInstall
    */
   public function onPostInstall() {
diff --git a/CRM/Utils/Hook.php b/CRM/Utils/Hook.php
index c44273c842..beec63c407 100644
--- a/CRM/Utils/Hook.php
+++ b/CRM/Utils/Hook.php
@@ -1865,15 +1865,41 @@ abstract class CRM_Utils_Hook {
   }
 
   /**
-   * This hook is called when a module-extension is installed.
-   * Each module will receive hook_civicrm_install during its own installation (but not during the
-   * installation of unrelated modules).
+   * Run early installation steps for an extension. Ex: Create new MySQL table.
+   *
+   * This dispatches directly to each new extension. You will only receive notices for your own installation.
+   *
+   * If multiple extensions are installed simultaneously, they will all run
+   * `hook_install`/`hook_enable` back-to-back (in order of dependency).
+   *
+   * This runs BEFORE refreshing major caches and services (such as
+   * `ManagedEntities` and `CRM_Logging_Schema`).
+   *
+   * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_install
    */
   public static function install() {
     // Actually invoke via CRM_Extension_Manager_Module::callHook
     throw new \RuntimeException(sprintf("The method %s::%s is just a documentation stub and should not be invoked directly.", __CLASS__, __FUNCTION__));
   }
 
+  /**
+   * Run later installation steps. Ex: Call a bespoke API-job for the first time.
+   *
+   * This dispatches directly to each new extension. You will only receive notices for your own installation.
+   *
+   * If multiple extensions are installed simultaneously, they will all run
+   * `hook_postInstall` back-to-back (in order of dependency).
+   *
+   * This runs AFTER refreshing major caches and services (such as
+   * `ManagedEntities` and `CRM_Logging_Schema`).
+   *
+   * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_postInstall
+   */
+  public static function postInstall() {
+    // Actually invoke via CRM_Extension_Manager_Module::callHook
+    throw new \RuntimeException(sprintf("The method %s::%s is just a documentation stub and should not be invoked directly.", __CLASS__, __FUNCTION__));
+  }
+
   /**
    * This hook is called when a module-extension is uninstalled.
    * Each module will receive hook_civicrm_uninstall during its own uninstallation (but not during the
-- 
2.25.1