Update vendor/docdown to parse more compliant jsdoc syntax.

Former-commit-id: cfd5d1a5eae3a2608ed49ea388c389fb1ea0e489

vendor/docdown/src/DocDown/MarkdownGenerator.php

@@ -12,7 +12,7 @@ class MarkdownGenerator {
    *
    * @static
    * @memberOf MarkdownGenerator
-   * @type String
+   * @type string
    */
   public $closeTag = "\n<!-- /div -->\n";
 
@@ -29,7 +29,7 @@ class MarkdownGenerator {
    *
    * @static
    * @memberOf MarkdownGenerator
-   * @type String
+   * @type string
    */
   public $openTag = "\n<!-- div -->\n";
 
@@ -45,7 +45,7 @@ class MarkdownGenerator {
    * The file's source code.
    *
    * @memberOf MarkdownGenerator
-   * @type String
+   * @type string
    */
   public $source = '';
 
@@ -55,8 +55,8 @@ class MarkdownGenerator {
    * The MarkdownGenerator constructor.
    *
    * @constructor
-   * @param {String} $source The source code to parse.
-   * @param {Array} $options The options array.
+   * @param {string} $source The source code to parse.
+   * @param {array} $options The options array.
    */
   public function __construct( $source, $options = array() ) {
     // juggle arguments
@@ -104,8 +104,8 @@ class MarkdownGenerator {
    * @private
    * @static
    * @memberOf MarkdownGenerator
-   * @param {String} $string The string to format.
-   * @returns {String} The formatted string.
+   * @param {string} $string The string to format.
+   * @returns {string} The formatted string.
    */
   private static function format( $string ) {
     $counter = 0;
@@ -138,22 +138,22 @@ class MarkdownGenerator {
    * @private
    * @static
    * @memberOf MarkdownGenerator
-   * @param {String} $string The string to modify.
-   * @param {Array|Object} $object The template object.
-   * @returns {String} The modified string.
+   * @param {string} $string The string to modify.
+   * @param {(array|object)} $object The template object.
+   * @returns {string} The modified string.
    */
   private static function interpolate( $string, $object ) {
     preg_match_all('/#\{([^}]+)\}/', $string, $tokens);
     $tokens = array_unique(array_pop($tokens));
 
     foreach ($tokens as $token) {
-      $pattern = '/#\{' . $token . '\}/';
+      $pattern = '/#\{' . preg_replace('/([.*+?^${}()|[\]\\\])/', '\\\$1', $token) . '\}/';
       $replacement = '';
 
       if (is_object($object)) {
         preg_match('/\(([^)]+?)\)$/', $token, $args);
         $args = preg_split('/,\s*/', array_pop($args));
-        $method = 'get' . ucfirst(str_replace('/\([^)]+?\)$/', '', $token));
+        $method = 'get' . ucfirst(preg_replace('/\([^)]+?\)$/', '', $token));
 
         if (method_exists($object, $method)) {
           $replacement = (string) call_user_func_array(array($object, $method), $args);
@@ -175,8 +175,8 @@ class MarkdownGenerator {
    *
    * @private
    * @memberOf MarkdownGenerator
-   * @param {Array} $result The result array to modify.
-   * @param {Array} $entries The entries to add to the `$result`.
+   * @param {array} $result The result array to modify.
+   * @param {array} $entries The entries to add to the `$result`.
    */
   private function addEntries( &$result, $entries ) {
     foreach ($entries as $entry) {
@@ -207,7 +207,7 @@ class MarkdownGenerator {
             'desc' => $param[2],
             'name' => $param[1],
             'num'  => $index + 1,
-            'type' => $param[0]
+            'type' => preg_replace('/(?<!\\\)(\*)/', '\\\$1', $param[0])
           ));
         }
       }
@@ -216,7 +216,10 @@ class MarkdownGenerator {
         array_push(
           $result, '',
           '#### Returns',
-          MarkdownGenerator::interpolate('(#{type}): #{desc}', array('desc' => $returns[1], 'type' => $returns[0]))
+          MarkdownGenerator::interpolate('(#{type}): #{desc}', array(
+            'desc' => $returns[1],
+            'type' => preg_replace('/(?<!\\\)(\*)/', '\\\$1', $returns[0])
+          ))
         );
       }
       // @example
@@ -232,13 +235,14 @@ class MarkdownGenerator {
    *
    * @private
    * @memberOf MarkdownGenerator
-   * @param {Number|Object} $entry The entry object.
-   * @param {String} $member The name of the member.
-   * @returns {String} The url hash.
+   * @param {(number|object)} $entry The entry object.
+   * @param {string} $member The name of the member.
+   * @returns {string} The url hash.
    */
   private function getHash( $entry, $member = '' ) {
     $entry = is_numeric($entry) ? $this->entries[$entry] : $entry;
     $member = !$member ? $entry->getMembers(0) : $member;
+
     $result = ($member ? $member . ($entry->isPlugin() ? 'prototype' : '') : '') . $entry->getCall();
     $result = preg_replace('/\(\[|\[\]/', '', $result);
     $result = preg_replace('/[\t =|\'"{}.()\]]/', '', $result);
@@ -251,8 +255,8 @@ class MarkdownGenerator {
    *
    * @private
    * @memberOf MarkdownGenerator
-   * @param {Number|Object} $entry The entry object.
-   * @returns {String} The url.
+   * @param {(number|object)} $entry The entry object.
+   * @returns {string} The url.
    */
   private function getLineUrl( $entry ) {
     $entry = is_numeric($entry) ? $this->entries($entry) : $entry;
@@ -264,8 +268,8 @@ class MarkdownGenerator {
    *
    * @private
    * @memberOf MarkdownGenerator
-   * @param {Number|Object} $entry The entry object.
-   * @returns {String} The separator.
+   * @param {(number|object)} $entry The entry object.
+   * @returns {string} The separator.
    */
   private function getSeparator( $entry ) {
     $entry = is_numeric($entry) ? $this->entries($entry) : $entry;
@@ -278,7 +282,7 @@ class MarkdownGenerator {
    * Generates Markdown from JSDoc entries.
    *
    * @memberOf MarkdownGenerator
-   * @returns {String} The rendered Markdown.
+   * @returns {string} The rendered Markdown.
    */
   public function generate() {
     $api = array();
@@ -311,7 +315,7 @@ class MarkdownGenerator {
         }
 
         // append entry to api member
-        if (!$member || $entry->isCtor() || ($entry->getType() == 'Object' &&
+        if (!$member || $entry->isCtor() || ($entry->getType() == 'object' &&
             !preg_match('/[=:]\s*(?:null|undefined)\s*[,;]?$/', $entry->entry))) {
 
           // assign the real entry, replacing the temporary entry if it exist
@@ -396,7 +400,7 @@ class MarkdownGenerator {
         foreach ($entry->{$kind} as $subentry) {
           $name = $subentry->getName();
           // functions w/o ALL-CAPs names are last
-          $sortBy['a'][] = $subentry->getType() == 'Function' && !preg_match('/^[A-Z_]+$/', $name);
+          $sortBy['a'][] = $subentry->getType() == 'function' && !preg_match('/^[A-Z_]+$/', $name);
           // ALL-CAPs properties first
           $sortBy['b'][] = preg_match('/^[A-Z_]+$/', $name);
           // lowercase alphanumeric sort
@@ -537,7 +541,7 @@ class MarkdownGenerator {
           $subentries = is_string($kind) ? $entry->{$kind} : array($kind);
 
           // add sub-entry name
-          if ($kind != 'static' && $entry->getType() != 'Object' &&
+          if ($kind != 'static' && $entry->getType() != 'object' &&
                 count($subentries) && $subentries[0] != $kind) {
             if ($kind == 'plugin') {
               $result[] = $closeTag;