Merge pull request #17368 from colemanw/api4suffix

[civicrm-core.git] / Civi / Api4 / Utils / ReflectionUtils.php

diff --git a/Civi/Api4/Utils/ReflectionUtils.php b/Civi/Api4/Utils/ReflectionUtils.php
index 58b3aab9519739266663209b324fdc25653e5b8a..0733b20f891fe5b26f63ed02dab49fb6ea81d4b2 100644 (file)
--- a/Civi/Api4/Utils/ReflectionUtils.php
+++ b/Civi/Api4/Utils/ReflectionUtils.php
@@ -20,11 +20,17 @@ class ReflectionUtils {
    * @param \Reflector|\ReflectionClass $reflection
    * @param string $type
    *   If we are not reflecting the class itself, specify "Method", "Property", etc.
-   *
+   * @param array $vars
+   *   Variable substitutions to perform in the docblock
    * @return array
    */
-  public static function getCodeDocs($reflection, $type = NULL) {
-    $docs = self::parseDocBlock($reflection->getDocComment());
+  public static function getCodeDocs($reflection, $type = NULL, $vars = []) {
+    $comment = $reflection->getDocComment();
+    foreach ($vars as $key => $val) {
+      $comment = str_replace('$' . strtoupper(\CRM_Utils_String::pluralize($key)), \CRM_Utils_String::pluralize($val), $comment);
+      $comment = str_replace('$' . strtoupper($key), $val, $comment);
+    }
+    $docs = self::parseDocBlock($comment);
 
     // Recurse into parent functions
     if (isset($docs['inheritDoc']) || isset($docs['inheritdoc'])) {
@@ -47,7 +53,7 @@ class ReflectionUtils {
       }
       if ($newReflection) {
         // Mix in
-        $additionalDocs = self::getCodeDocs($newReflection, $type);
+        $additionalDocs = self::getCodeDocs($newReflection, $type, $vars);
         if (!empty($docs['comment']) && !empty($additionalDocs['comment'])) {
           $docs['comment'] .= "\n\n" . $additionalDocs['comment'];
         }
@@ -68,19 +74,25 @@ class ReflectionUtils {
       if (!$num || strpos($line, '*/') !== FALSE) {
         continue;
       }
-      $line = preg_replace('/[ ]+/', ' ', ltrim(trim($line), '* '));
-      if (strpos($line, '@') === 0) {
-        $words = explode(' ', $line);
-        $key = substr(array_shift($words), 1);
+      $line = ltrim(trim($line), '*');
+      if (strlen($line) && $line[0] === ' ') {
+        $line = substr($line, 1);
+      }
+      if (strpos(ltrim($line), '@') === 0) {
+        $words = explode(' ', ltrim($line, ' @'));
+        $key = array_shift($words);
         $param = NULL;
         if ($key == 'var') {
           $info['type'] = explode('|', $words[0]);
         }
+        elseif ($key == 'return') {
+          $info['return'] = explode('|', $words[0]);
+        }
         elseif ($key == 'options') {
           $val = str_replace(', ', ',', implode(' ', $words));
           $info['options'] = explode(',', $val);
         }
-        elseif ($key == 'throws') {
+        elseif ($key == 'throws' || $key == 'see') {
           $info[$key][] = implode(' ', $words);
         }
         elseif ($key == 'param' && $words) {
@@ -102,19 +114,26 @@ class ReflectionUtils {
         $info['params'][$param]['comment'] .= $line . "\n";
       }
       elseif ($num == 1) {
-        $info['description'] = $line;
+        $info['description'] = ucfirst($line);
       }
       elseif (!$line) {
         if (isset($info['comment'])) {
           $info['comment'] .= "\n";
         }
+        else {
+          $info['comment'] = NULL;
+        }
+      }
+      // For multi-line description.
+      elseif (count($info) === 1 && isset($info['description']) && substr($info['description'], -1) !== '.') {
+        $info['description'] .= ' ' . $line;
       }
       else {
         $info['comment'] = isset($info['comment']) ? "{$info['comment']}\n$line" : $line;
       }
     }
     if (isset($info['comment'])) {
-      $info['comment'] = trim($info['comment']);
+      $info['comment'] = rtrim($info['comment']);
     }
     return $info;
   }