From 829b5a4e624d4c83b1277ab652fdb55f17c1d6ba Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Thu, 23 Feb 2023 23:43:10 -0800
Subject: [PATCH] crmURL - Add examples and whitespace. Crosslink docs.

---
 CRM/Core/Smarty/plugins/function.crmURL.php | 43 ++++++++++++---------
 CRM/Utils/System.php                        |  9 +++--
 2 files changed, 29 insertions(+), 23 deletions(-)

diff --git a/CRM/Core/Smarty/plugins/function.crmURL.php b/CRM/Core/Smarty/plugins/function.crmURL.php
index 540502d94a..810e3b4bc1 100644
--- a/CRM/Core/Smarty/plugins/function.crmURL.php
+++ b/CRM/Core/Smarty/plugins/function.crmURL.php
@@ -17,27 +17,32 @@
  */
 
 /**
- * Generate a url
+ * Generate a URL.
  *
- * @param array $params
- *   The values to construct the url.
- *   - p  string $path
- *   The path being linked to, such as "civicrm/add".
- *   - q array|string $query
- *   A query string to append to the link, or an array of key-value pairs.
- *   -a bool $absolute
- *   Whether to force the output to be an absolute link (beginning with a
- *   URI-scheme such as 'http:'). Useful for links that will be displayed
- *   outside the site, such as in an RSS feed.
- *   -f  string $fragment
- *   A fragment identifier (named anchor) to append to the link.
- *   -h  bool $htmlize
- *   Whether to encode special html characters such as &.
- *   -fe bool $frontend
- *   This link should be to the CMS front end (applies to WP & Joomla).
- *   -fb bool $forceBackend
- *   This link should be to the CMS back end (applies to WP & Joomla).
+ * Ex: `{crmURL p='civicrm/acl/entityrole' q='reset=1'}`
+ * Ex: `{crmURL p='civicrm/profile/create' q='id=123&reset=1' fe=1}`
+ *
+ * Each URL component uses an abbreviation (e.g. "p"<=>"path"; "q"<=>"query").
  *
+ * @param array $params
+ *   List of URL properties.
+ *   - "p" (string $path)
+ *     The path being linked to, such as "civicrm/add".
+ *   - "q" (array|string $query)
+ *     A query string to append to the link, or an array of key-value pairs.
+ *   - "a" (bool $absolute)
+ *     Whether to force the output to be an absolute link (beginning with a
+ *     URI-scheme such as 'http:'). Useful for links that will be displayed
+ *     outside the site, such as in an RSS feed.
+ *   - "f" (string $fragment)
+ *     A "#" fragment to append to the link. This could a named anchor (as
+ *     in `#section2`) or a client-side route (as in `#/mailing/new`).
+ *   - "h" (bool $htmlize)
+ *     Whether to encode special html characters such as &.
+ *   - "fe" (bool $frontend)
+ *     This link should be to the CMS front end (applies to WP & Joomla).
+ *   - "fb" (bool $forceBackend)
+ *     This link should be to the CMS back end (applies to WP & Joomla).
  * @return string
  */
 function smarty_function_crmURL($params) {
diff --git a/CRM/Utils/System.php b/CRM/Utils/System.php
index 83652a6fb7..a280cf539a 100644
--- a/CRM/Utils/System.php
+++ b/CRM/Utils/System.php
@@ -445,13 +445,14 @@ class CRM_Utils_System {
   }
 
   /**
-   * Called from a template to compose a url.
+   * Compose a URL. This is a wrapper for `url()` which is optimized for use in Smarty.
    *
+   * @see \smarty_function_crmURL()
    * @param array $params
-   *   List of parameters.
-   *
+   *   URL properties. Keys are abbreviated ("p"<=>"path").
+   *   See Smarty doc for full details.
    * @return string
-   *   url
+   *   URL
    */
   public static function crmURL($params) {
     $p = $params['p'] ?? NULL;
-- 
2.25.1