Update vendors.

Former-commit-id: ad3284b1e77cfb0b17af99e0ddaf00618e4485b7

vendor/docdown/src/DocDown/Alias.php

@@ -0,0 +1,204 @@
+<?php
+
+/**
+ * A class to represent a JSDoc entry alias.
+ */
+class Alias {
+
+  /**
+   * The alias owner.
+   *
+   * @memberOf Alias
+   * @type Object
+   */
+  public $owner;
+
+  /*--------------------------------------------------------------------------*/
+
+  /**
+   * The Alias constructor.
+   *
+   * @constructor
+   * @param {String} $name The alias name.
+   * @param {Object} $owner The alias owner.
+   */
+  public function __construct($name, $owner) {
+    $this->owner = $owner;
+    $this->_name = $name;
+    $this->_call = $owner->getCall();
+    $this->_desc = $owner->getDesc();
+    $this->_example = $owner->getExample();
+    $this->_lineNumber = $owner->getLineNumber();
+    $this->_members = $owner->getMembers();
+    $this->_params = $owner->getParams();
+    $this->_returns = $owner->getReturns();
+    $this->_type = $owner->getType();
+    $this->_isCtor = $owner->isCtor();
+    $this->_isPlugin = $owner->isPlugin();
+    $this->_isPrivate = $owner->isPrivate();
+    $this->_isStatic = $owner->isStatic();
+  }
+
+  /*--------------------------------------------------------------------------*/
+
+  /**
+   * Extracts the entry's `alias` objects.
+   *
+   * @memberOf Alias
+   * @param {Number} $index The index of the array value to return.
+   * @returns {Array|String} The entry's `alias` objects.
+   */
+  public function getAliases( $index = null ) {
+    $result = array();
+    return $index !== null
+      ? @$result[$index]
+      : $result;
+  }
+
+  /**
+   * Extracts the function call from the owner entry.
+   *
+   * @memberOf Alias
+   * @returns {String} The function call.
+   */
+  public function getCall() {
+    return $this->_call;
+  }
+
+  /**
+   * Extracts the owner entry's description.
+   *
+   * @memberOf Alias
+   * @returns {String} The owner entry's description.
+   */
+  public function getDesc() {
+    return $this->_desc;
+  }
+
+  /**
+   * Extracts the owner entry's `example` data.
+   *
+   * @memberOf Alias
+   * @returns {String} The owner entry's `example` data.
+   */
+  public function getExample() {
+    return $this->_example;
+  }
+
+  /**
+   * Resolves the owner entry's line number.
+   *
+   * @memberOf Alias
+   * @returns {Number} The owner entry's line number.
+   */
+  public function getLineNumber() {
+    return $this->_lineNumber;
+  }
+
+  /**
+   * Extracts the owner entry's `member` data.
+   *
+   * @memberOf Alias
+   * @param {Number} $index The index of the array value to return.
+   * @returns {Array|String} The owner entry's `member` data.
+   */
+  public function getMembers( $index = null ) {
+    return $index !== null
+      ? @$this->_members[$index]
+      : $this->_members;
+  }
+
+  /**
+   * Extracts the owner entry's `name` data.
+   *
+   * @memberOf Alias
+   * @returns {String} The owner entry's `name` data.
+   */
+  public function getName() {
+    return $this->_name;
+  }
+
+  /**
+   * Extracts the owner entry's `param` data.
+   *
+   * @memberOf Alias
+   * @param {Number} $index The index of the array value to return.
+   * @returns {Array} The owner entry's `param` data.
+   */
+  public function getParams( $index = null ) {
+    return $index !== null
+      ? @$this->_params[$index]
+      : $this->_params;
+  }
+
+  /**
+   * Extracts the owner entry's `returns` data.
+   *
+   * @memberOf Alias
+   * @returns {String} The owner entry's `returns` data.
+   */
+  public function getReturns() {
+    return $this->_returns;
+  }
+
+  /**
+   * Extracts the owner entry's `type` data.
+   *
+   * @memberOf Alias
+   * @returns {String} The owner entry's `type` data.
+   */
+  public function getType() {
+    return $this->_type;
+  }
+
+  /**
+   * Checks if the entry is an alias.
+   *
+   * @memberOf Alias
+   * @returns {Boolean} Returns `true`.
+   */
+  public function isAlias() {
+    return true;
+  }
+
+  /**
+   * Checks if the owner entry is a constructor.
+   *
+   * @memberOf Alias
+   * @returns {Boolean} Returns `true` if a constructor, else `false`.
+   */
+  public function isCtor() {
+    return $this->_isCtor;
+  }
+
+  /**
+   * Checks if the owner entry *is* assigned to a prototype.
+   *
+   * @memberOf Alias
+   * @returns {Boolean} Returns `true` if assigned to a prototype, else `false`.
+   */
+  public function isPlugin() {
+    return $this->_isPlugin;
+  }
+
+  /**
+   * Checks if the owner entry is private.
+   *
+   * @memberOf Alias
+   * @returns {Boolean} Returns `true` if private, else `false`.
+   */
+  public function isPrivate() {
+    return $this->_isPrivate;
+  }
+
+  /**
+   * Checks if the owner entry is *not* assigned to a prototype.
+   *
+   * @memberOf Alias
+   * @returns {Boolean} Returns `true` if not assigned to a prototype, else `false`.
+   */
+  public function isStatic() {
+    return $this->_isStatic;
+  }
+}
+?>

vendor/docdown/src/DocDown/Entry.php

@@ -1,5 +1,7 @@
 <?php
 
+require(dirname(__FILE__) . "/Alias.php");
+
 /**
  * A class to simplify parsing a single JSDoc entry.
  */
@@ -37,7 +39,7 @@ class Entry {
    * @constructor
    * @param {String} $entry The documentation entry to analyse.
    * @param {String} $source The source code.
-   * @param {String} $lang The language highlighter used for code examples.
+   * @param {String} [$lang ='js'] The language highlighter used for code examples.
    */
   public function __construct( $entry, $source, $lang = 'js' ) {
     $this->entry = $entry;
@@ -70,16 +72,45 @@ class Entry {
    * @returns {Boolean} Returns `true` if the entry is a function reference, else `false`.
    */
   private function isFunction() {
-    return !!(
-      $this->isCtor() ||
-      count($this->getParams()) ||
-      count($this->getReturns()) ||
-      preg_match('/\*\s*@function\b/', $this->entry)
-    );
+    if (!isset($this->_isFunction)) {
+      $this->_isFunction = !!(
+        $this->isCtor() ||
+        count($this->getParams()) ||
+        count($this->getReturns()) ||
+        preg_match('/\*\s*@function\b/', $this->entry)
+      );
+    }
+    return $this->_isFunction;
   }
 
   /*--------------------------------------------------------------------------*/
 
+  /**
+   * Extracts the entry's `alias` objects.
+   *
+   * @memberOf Entry
+   * @param {Number} $index The index of the array value to return.
+   * @returns {Array|String} The entry's `alias` objects.
+   */
+  public function getAliases( $index = null ) {
+    if (!isset($this->_aliases)) {
+      preg_match('#\*\s*@alias\s+([^\n]+)#', $this->entry, $result);
+
+      if (count($result)) {
+        $result = trim(preg_replace('/(?:^|\n)\s*\* ?/', ' ', $result[1]));
+        $result = preg_split('/,\s*/', $result);
+
+        foreach ($result as $resultIndex => $value) {
+          $result[$resultIndex] = new Alias($value, $this);
+        }
+      }
+      $this->_aliases = $result;
+    }
+    return $index !== null
+      ? @$this->_aliases[$index]
+      : $this->_aliases;
+  }
+
   /**
    * Extracts the function call from the entry.
    *
@@ -87,6 +118,10 @@ class Entry {
    * @returns {String} The function call.
    */
   public function getCall() {
+    if (isset($this->_call)) {
+      return $this->_call;
+    }
+
     preg_match('#\*/\s*(?:function ([^(]*)|(.*?)(?=[:=,]|return\b))#', $this->entry, $result);
     if ($result = array_pop($result)) {
       $result = array_pop(explode('var ', trim(trim(array_pop(explode('.', $result))), "'")));
@@ -111,176 +146,239 @@ class Entry {
       $result = $name .'('. implode(array_slice($result, 1), ', ') .')';
       $result = str_replace(', [', ' [, ', str_replace('], [', ', ', $result));
     }
-    return $result ? $result : $name;
+
+    $this->_call = $result ? $result : $name;
+    return $this->_call;
   }
 
   /**
-   * Extracts the entry description.
+   * Extracts the entry's description.
    *
    * @memberOf Entry
-   * @returns {String} The entry description.
+   * @returns {String} The entry's description.
    */
   public function getDesc() {
+    if (isset($this->_desc)) {
+      return $this->_desc;
+    }
+
     preg_match('#/\*\*(?:\s*\*)?([\s\S]*?)(?=\*\s\@[a-z]|\*/)#', $this->entry, $result);
     if (count($result)) {
       $type = $this->getType();
       $result = trim(preg_replace('/(?:^|\n)\s*\* ?/', ' ', $result[1]));
       $result = ($type == 'Function' ? '' : '(' . str_replace('|', ', ', trim($type, '{}')) . '): ') . $result;
     }
+    $this->_desc = $result;
     return $result;
   }
 
   /**
-   * Extracts the entry `example` data.
+   * Extracts the entry's `example` data.
    *
    * @memberOf Entry
-   * @returns {String} The entry `example` data.
+   * @returns {String} The entry's `example` data.
    */
   public function getExample() {
+    if (isset($this->_example)) {
+      return $this->_example;
+    }
+
     preg_match('#\*\s*@example\s+([\s\S]*?)(?=\*\s\@[a-z]|\*/)#', $this->entry, $result);
     if (count($result)) {
       $result = trim(preg_replace('/(?:^|\n)\s*\* ?/', "\n", $result[1]));
       $result = '```' . $this->lang . "\n" . $result . "\n```";
     }
+    $this->_example = $result;
     return $result;
   }
 
   /**
-   * Resolves the line number of the entry.
+   * Resolves the entry's line number.
    *
    * @memberOf Entry
-   * @returns {Number} The line number.
+   * @returns {Number} The entry's line number.
    */
   public function getLineNumber() {
-    preg_match_all('/\n/', substr($this->source, 0, strrpos($this->source, $this->entry) + strlen($this->entry)), $lines);
-    return count(array_pop($lines)) + 1;
+    if (!isset($this->_lineNumber)) {
+      preg_match_all('/\n/', substr($this->source, 0, strrpos($this->source, $this->entry) + strlen($this->entry)), $lines);
+      $this->_lineNumber = count(array_pop($lines)) + 1;
+    }
+    return $this->_lineNumber;
   }
 
   /**
-   * Extracts the entry `member` data.
+   * Extracts the entry's `member` data.
    *
    * @memberOf Entry
    * @param {Number} $index The index of the array value to return.
-   * @returns {Array|String} The entry `member` data.
+   * @returns {Array|String} The entry's `member` data.
    */
   public function getMembers( $index = null ) {
-    preg_match('#\*\s*@member(?:Of)?\s+([^\n]+)#', $this->entry, $result);
-    if (count($result)) {
-      $result = trim(preg_replace('/(?:^|\n)\s*\* ?/', ' ', $result[1]));
-      $result = preg_split('/,\s*/', $result);
+    if (!isset($this->_members)) {
+      preg_match('#\*\s*@member(?:Of)?\s+([^\n]+)#', $this->entry, $result);
+      if (count($result)) {
+        $result = trim(preg_replace('/(?:^|\n)\s*\* ?/', ' ', $result[1]));
+        $result = preg_split('/,\s*/', $result);
+      }
+      $this->_members = $result;
     }
-    return $index !== null ? @$result[$index] : $result;
+    return $index !== null
+      ? @$this->_members[$index]
+      : $this->_members;
   }
 
   /**
-   * Extracts the entry `name` data.
+   * Extracts the entry's `name` data.
    *
    * @memberOf Entry
-   * @returns {String} The entry `name` data.
+   * @returns {String} The entry's `name` data.
    */
   public function getName() {
+    if (isset($this->_name)) {
+      return $this->_name;
+    }
+
     preg_match('#\*\s*@name\s+([^\n]+)#', $this->entry, $result);
     if (count($result)) {
       $result = trim(preg_replace('/(?:^|\n)\s*\* ?/', ' ', $result[1]));
     } else {
       $result = array_shift(explode('(', $this->getCall()));
     }
+    $this->_name = $result;
     return $result;
   }
 
   /**
-   * Extracts the entry `param` data.
+   * Extracts the entry's `param` data.
    *
    * @memberOf Entry
    * @param {Number} $index The index of the array value to return.
-   * @returns {Array} The entry `param` data.
+   * @returns {Array} The entry's `param` data.
    */
   public function getParams( $index = null ) {
-    preg_match_all('#\*\s*@param\s+\{([^}]+)\}\s+(\[.+\]|[$\w|]+(?:\[.+\])?)\s+([\s\S]*?)(?=\*\s\@[a-z]|\*/)#i', $this->entry, $result);
-    if (count($result = array_filter(array_slice($result, 1)))) {
-      // repurpose array
-      foreach ($result as $param) {
-        foreach ($param as $key => $value) {
-          if (!is_array($result[0][$key])) {
-            $result[0][$key] = array();
+    if (!isset($this->_params)) {
+      preg_match_all('#\*\s*@param\s+\{([^}]+)\}\s+(\[.+\]|[$\w|]+(?:\[.+\])?)\s+([\s\S]*?)(?=\*\s\@[a-z]|\*/)#i', $this->entry, $result);
+      if (count($result = array_filter(array_slice($result, 1)))) {
+        // repurpose array
+        foreach ($result as $param) {
+          foreach ($param as $key => $value) {
+            if (!is_array($result[0][$key])) {
+              $result[0][$key] = array();
+            }
+            $result[0][$key][] = trim(preg_replace('/(?:^|\n)\s*\* */', ' ', $value));
           }
-          $result[0][$key][] = trim(preg_replace('/(?:^|\n)\s*\* */', ' ', $value));
         }
+        $result = $result[0];
       }
-      $result = $result[0];
+      $this->_params = $result;
     }
-    return $index !== null ? @$result[$index] : $result;
+    return $index !== null
+      ? @$this->_params[$index]
+      : $this->_params;
   }
 
   /**
-   * Extracts the entry `returns` data.
+   * Extracts the entry's `returns` data.
    *
    * @memberOf Entry
-   * @returns {String} The entry `returns` data.
+   * @returns {String} The entry's `returns` data.
    */
   public function getReturns() {
+    if (isset($this->_returns)) {
+      return $this->_returns;
+    }
+
     preg_match('#\*\s*@returns\s+\{([^}]+)\}\s+([\s\S]*?)(?=\*\s\@[a-z]|\*/)#', $this->entry, $result);
     if (count($result)) {
       $result = array_map('trim', array_slice($result, 1));
       $result[0] = str_replace('|', ', ', $result[0]);
       $result[1] = preg_replace('/(?:^|\n)\s*\* ?/', ' ', $result[1]);
     }
+    $this->_returns = $result;
     return $result;
   }
 
   /**
-   * Extracts the entry `type` data.
+   * Extracts the entry's `type` data.
    *
    * @memberOf Entry
-   * @returns {String} The entry `type` data.
+   * @returns {String} The entry's `type` data.
    */
   public function getType() {
+    if (isset($this->_type)) {
+      return $this->_type;
+    }
+
     preg_match('#\*\s*@type\s+([^\n]+)#', $this->entry, $result);
     if (count($result)) {
       $result = trim(preg_replace('/(?:^|\n)\s*\* ?/', ' ', $result[1]));
     } else {
       $result = $this->isFunction() ? 'Function' : 'Unknown';
     }
+    $this->_type = $result;
     return $result;
   }
 
   /**
-   * Checks if an entry is a constructor.
+   * Checks if the entry is an alias.
    *
    * @memberOf Entry
-   * @returns {Boolean} Returns true if a constructor, else false.
+   * @returns {Boolean} Returns `false`.
+   */
+  public function isAlias() {
+    return false;
+  }
+
+  /**
+   * Checks if the entry is a constructor.
+   *
+   * @memberOf Entry
+   * @returns {Boolean} Returns `true` if a constructor, else `false`.
    */
   public function isCtor() {
-    return !!preg_match('/\*\s*@constructor\b/', $this->entry);
+    if (!isset($this->_isCtor)) {
+      $this->_isCtor = !!preg_match('/\*\s*@constructor\b/', $this->entry);
+    }
+    return $this->_isCtor;
   }
 
   /**
-   * Checks if an entry *is* assigned to a prototype.
+   * Checks if the entry *is* assigned to a prototype.
    *
    * @memberOf Entry
-   * @returns {Boolean} Returns true if assigned to a prototype, else false.
+   * @returns {Boolean} Returns `true` if assigned to a prototype, else `false`.
    */
   public function isPlugin() {
-    return !$this->isCtor() && !$this->isPrivate() && !$this->isStatic();
+    if (!isset($this->_isPlugin)) {
+      $this->_isPlugin = !$this->isCtor() && !$this->isPrivate() && !$this->isStatic();
+    }
+    return $this->_isPlugin;
   }
 
   /**
-   * Checks if an entry is private.
+   * Checks if the entry is private.
    *
    * @memberOf Entry
-   * @returns {Boolean} Returns true if private, else false.
+   * @returns {Boolean} Returns `true` if private, else `false`.
    */
   public function isPrivate() {
-    return !!preg_match('/\*\s*@private\b/', $this->entry) || strrpos($this->entry, '@') === false;
+    if (!isset($this->_isPrivate)) {
+      $this->_isPrivate = !!preg_match('/\*\s*@private\b/', $this->entry) || strrpos($this->entry, '@') === false;
+    }
+    return $this->_isPrivate;
   }
 
   /**
-   * Checks if an entry is *not* assigned to a prototype.
+   * Checks if the entry is *not* assigned to a prototype.
    *
    * @memberOf Entry
-   * @returns {Boolean} Returns true if not assigned to a prototype, else false.
+   * @returns {Boolean} Returns `true` if not assigned to a prototype, else `false`.
    */
   public function isStatic() {
+    if (isset($this->_isStatic)) {
+      return $this->_isStatic;
+    }
+
     $public = !$this->isPrivate();
     $result = $public && !!preg_match('/\*\s*@static\b/', $this->entry);
 
@@ -298,6 +396,7 @@ class Entry {
         $result = true;
       }
     }
+    $this->_isStatic = $result;
     return $result;
   }
 }

vendor/docdown/src/DocDown/Generator.php

@@ -221,22 +221,39 @@ class Generator {
         foreach ($members as $member) {
           // create api category arrays
           if (!isset($api[$member]) && $member) {
+            // create temporary entry to be replaced later
             $api[$member] = new Entry('', '', $entry->lang);
             $api[$member]->static = array();
             $api[$member]->plugin = array();
           }
+
           // append entry to api category
           if (!$member || $entry->isCtor() || ($entry->getType() == 'Object' &&
               !preg_match('/[=:]\s*null\s*[,;]?$/', $entry->entry))) {
+
+            // assign the real entry, replacing the temporary entry if it exist
             $member = ($member ? $member . ($entry->isPlugin() ? '#' : '.') : '') . $name;
             $entry->static = @$api[$member] ? $api[$member]->static : array();
             $entry->plugin = @$api[$member] ? $api[$member]->plugin : array();
-            $api[$member]  = $entry;
+
+            $api[$member] = $entry;
+            foreach ($entry->getAliases() as $alias) {
+              $api[$member] = $alias;
+              $alias->static = array();
+              $alias->plugin = array();
+            }
           }
           else if ($entry->isStatic()) {
             $api[$member]->static[] = $entry;
-          } else if (!$entry->isCtor()) {
+            foreach ($entry->getAliases() as $alias) {
+              $api[$member]->static[] = $alias;
+            }
+          }
+          else if (!$entry->isCtor()) {
             $api[$member]->plugin[] = $entry;
+            foreach ($entry->getAliases() as $alias) {
+              $api[$member]->plugin[] = $alias;
+            }
           }
         }
       }
@@ -346,6 +363,11 @@ class Generator {
     $result[] = $openTag;
 
     foreach ($api as $entry) {
+      // skip aliases
+      if ($entry->isAlias()) {
+        continue;
+      }
+
       // add root entry
       $member = $entry->member . $entry->getName();
       $compiling = $compiling ? ($result[] = $closeTag) : true;
@@ -370,6 +392,11 @@ class Generator {
 
         // body
         foreach ($subentries as $subentry) {
+          // skip aliases
+          if ($subentry->isAlias()) {
+            continue;
+          }
+
           // description
           array_push(
             $result,
@@ -377,6 +404,14 @@ class Generator {
             Generator::interpolate("### <a id=\"#{hash}\"></a>`#{member}#{separator}#{call}`\n<a href=\"##{hash}\">#</a> [&#x24C8;](#{href} \"View in source\") [&#x24C9;][1]\n\n#{desc}", $subentry)
           );
 
+          // @alias
+          if (count($aliases = $subentry->getAliases())) {
+            array_push($result, '', '#### Aliases');
+            foreach ($aliases as $index => $alias) {
+              $aliases[$index] = $alias->getName();
+            }
+            $result[] = implode(', ', $aliases);
+          }
           // @param
           if (count($params = $subentry->getParams())) {
             array_push($result, '', '#### Arguments');