Mirrors/lodash
1
0
Fork 0
mirror of https://github.com/whoisclebs/lodash.git synced 2026-02-05 09:27:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update vendor/docdown to parse more compliant jsdoc syntax.

Browse Source 
Former-commit-id: cfd5d1a5eae3a2608ed49ea388c389fb1ea0e489
This commit is contained in:
John-David Dalton
2013-08-25 20:39:12 -07:00
parent a18be78bd3
commit a820ee4c82
5 changed files with 776 additions and 769 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1348
doc/README.md
View File

File diff suppressed because it is too large Load Diff

4
vendor/docdown/docdown.php vendored
View File

@@ -9,8 +9,8 @@ require(dirname(__FILE__) . '/src/DocDown/MarkdownGenerator.php');
/**
* Generates Markdown from JSDoc entries in a given file.
*
* @param {Array} [$options=array()] The options array.
* @returns {String} The generated Markdown.
* @param {array} [$options=array()] The options array.
* @returns {string} The generated Markdown.
* @example
*
* // specify a file path

44
vendor/docdown/src/DocDown/Alias.php vendored
View File

@@ -19,8 +19,8 @@ class Alias {
* The Alias constructor.
*
* @constructor
* @param {String} $name The alias name.
* @param {Object} $owner The alias owner.
* @param {string} $name The alias name.
* @param {object} $owner The alias owner.
*/
public function __construct( $name, $owner ) {
$this->owner = $owner;
@@ -47,8 +47,8 @@ class Alias {
* 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.
* @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();
@@ -61,7 +61,7 @@ class Alias {
* Extracts the function call from the owner entry.
*
* @memberOf Alias
* @returns {String} The function call.
* @returns {string} The function call.
*/
public function getCall() {
return $this->_call;
@@ -71,7 +71,7 @@ class Alias {
* Extracts the owner entry's `category` data.
*
* @memberOf Alias
* @returns {String} The owner entry's `category` data.
* @returns {string} The owner entry's `category` data.
*/
public function getCategory() {
return $this->_category;
@@ -81,7 +81,7 @@ class Alias {
* Extracts the owner entry's description.
*
* @memberOf Alias
* @returns {String} The owner entry's description.
* @returns {string} The owner entry's description.
*/
public function getDesc() {
return $this->_desc;
@@ -91,7 +91,7 @@ class Alias {
* Extracts the owner entry's `example` data.
*
* @memberOf Alias
* @returns {String} The owner entry's `example` data.
* @returns {string} The owner entry's `example` data.
*/
public function getExample() {
return $this->_example;
@@ -101,7 +101,7 @@ class Alias {
* Checks if the entry is an alias.
*
* @memberOf Alias
* @returns {Boolean} Returns `true`.
* @returns {boolean} Returns `true`.
*/
public function isAlias() {
return true;
@@ -111,7 +111,7 @@ class Alias {
* Checks if the owner entry is a constructor.
*
* @memberOf Alias
* @returns {Boolean} Returns `true` if a constructor, else `false`.
* @returns {boolean} Returns `true` if a constructor, else `false`.
*/
public function isCtor() {
return $this->_isCtor;
@@ -121,7 +121,7 @@ class Alias {
* Checks if the owner entry is a license.
*
* @memberOf Alias
* @returns {Boolean} Returns `true` if a license, else `false`.
* @returns {boolean} Returns `true` if a license, else `false`.
*/
public function isLicense() {
return $this->_isLicense;
@@ -131,7 +131,7 @@ class Alias {
* Checks if the owner entry *is* assigned to a prototype.
*
* @memberOf Alias
* @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->_isPlugin;
@@ -141,7 +141,7 @@ class Alias {
* Checks if the owner entry is private.
*
* @memberOf Alias
* @returns {Boolean} Returns `true` if private, else `false`.
* @returns {boolean} Returns `true` if private, else `false`.
*/
public function isPrivate() {
return $this->_isPrivate;
@@ -151,7 +151,7 @@ class Alias {
* 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`.
* @returns {boolean} Returns `true` if not assigned to a prototype, else `false`.
*/
public function isStatic() {
return $this->_isStatic;
@@ -161,7 +161,7 @@ class Alias {
* Resolves the owner entry's line number.
*
* @memberOf Alias
* @returns {Number} The owner entry's line number.
* @returns {number} The owner entry's line number.
*/
public function getLineNumber() {
return $this->_lineNumber;
@@ -171,8 +171,8 @@ class Alias {
* 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.
* @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
@@ -184,7 +184,7 @@ class Alias {
* Extracts the owner entry's `name` data.
*
* @memberOf Alias
* @returns {String} The owner entry's `name` data.
* @returns {string} The owner entry's `name` data.
*/
public function getName() {
return $this->_name;
@@ -194,8 +194,8 @@ class Alias {
* 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.
* @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
@@ -207,7 +207,7 @@ class Alias {
* Extracts the owner entry's `returns` data.
*
* @memberOf Alias
* @returns {String} The owner entry's `returns` data.
* @returns {string} The owner entry's `returns` data.
*/
public function getReturns() {
return $this->_returns;
@@ -217,7 +217,7 @@ class Alias {
* Extracts the owner entry's `type` data.
*
* @memberOf Alias
* @returns {String} The owner entry's `type` data.
* @returns {string} The owner entry's `type` data.
*/
public function getType() {
return $this->_type;

91
vendor/docdown/src/DocDown/Entry.php vendored
View File

@@ -11,7 +11,7 @@ class Entry {
* The documentation entry.
*
* @memberOf Entry
* @type String
* @type string
*/
public $entry = '';
@@ -19,7 +19,7 @@ class Entry {
* The language highlighter used for code examples.
*
* @memberOf Entry
* @type String
* @type string
*/
public $lang = '';
@@ -27,7 +27,7 @@ class Entry {
* The source code.
*
* @memberOf Entry
* @type String
* @type string
*/
public $source = '';
@@ -37,9 +37,9 @@ class Entry {
* The Entry constructor.
*
* @constructor
* @param {String} $entry The documentation entry to analyse.
* @param {String} $source The source code.
* @param {String} [$lang ='js'] The language highlighter used for code examples.
* @param {string} $entry The documentation entry to analyse.
* @param {string} $source The source code.
* @param {string} [$lang ='js'] The language highlighter used for code examples.
*/
public function __construct( $entry, $source, $lang = 'js' ) {
$this->entry = $entry;
@@ -54,8 +54,8 @@ class Entry {
*
* @static
* @memberOf Entry
* @param {String} $source The source code.
* @returns {Array} The array of entries.
* @param {string} $source The source code.
* @returns {array} The array of entries.
*/
public static function getEntries( $source ) {
preg_match_all('#/\*\*(?![-!])[\s\S]*?\*/\s*.+#', $source, $result);
@@ -69,7 +69,7 @@ class Entry {
*
* @private
* @memberOf Entry
* @returns {Boolean} Returns `true` if the entry is a function reference, else `false`.
* @returns {boolean} Returns `true` if the entry is a function reference, else `false`.
*/
private function isFunction() {
if (!isset($this->_isFunction)) {
@@ -89,8 +89,8 @@ class Entry {
* 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.
* @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)) {
@@ -116,7 +116,7 @@ class Entry {
* Extracts the function call from the entry.
*
* @memberOf Entry
* @returns {String} The function call.
* @returns {string} The function call.
*/
public function getCall() {
if (isset($this->_call)) {
@@ -140,12 +140,12 @@ class Entry {
// compose parts
$result = array($result);
$params = $this->getParams();
foreach ($params as $param) {
$result[] = $param[1];
}
// format
$result = $name .'('. implode(array_slice($result, 1), ', ') .')';
$result = str_replace(', [', ' [, ', str_replace('], [', ', ', $result));
}
$this->_call = $result ? $result : $name;
@@ -156,7 +156,7 @@ class Entry {
* Extracts the entry's `category` data.
*
* @memberOf Entry
* @returns {String} The entry's `category` data.
* @returns {string} The entry's `category` data.
*/
public function getCategory() {
if (isset($this->_category)) {
@@ -167,7 +167,7 @@ class Entry {
if (count($result)) {
$result = trim(preg_replace('/(?:^|\n)[\t ]*\*[\t ]?/', ' ', $result[1]));
} else {
$result = $this->getType() == 'Function' ? 'Methods' : 'Properties';
$result = $this->getType() == 'function' ? 'Methods' : 'Properties';
}
$this->_category = $result;
return $result;
@@ -177,7 +177,7 @@ class Entry {
* Extracts the entry's description.
*
* @memberOf Entry
* @returns {String} The entry's description.
* @returns {string} The entry's description.
*/
public function getDesc() {
if (isset($this->_desc)) {
@@ -191,7 +191,7 @@ class Entry {
$result = preg_replace('/(?:^|\n)[\t ]*\*\n[\t ]*\*[\t ]*/', "\n\n", $result);
$result = preg_replace('/(?:^|\n)[\t ]*\*[\t ]?/', ' ', $result);
$result = trim($result);
$result = ($type == 'Function' ? '' : '(' . str_replace('|', ', ', trim($type, '{}')) . '): ') . $result;
$result = ($type == 'function' ? '' : '(' . str_replace('|', ', ', trim($type, '{}')) . '): ') . $result;
}
$this->_desc = $result;
return $result;
@@ -201,7 +201,7 @@ class Entry {
* Extracts the entry's `example` data.
*
* @memberOf Entry
* @returns {String} The entry's `example` data.
* @returns {string} The entry's `example` data.
*/
public function getExample() {
if (isset($this->_example)) {
@@ -221,7 +221,7 @@ class Entry {
* Checks if the entry is an alias.
*
* @memberOf Entry
* @returns {Boolean} Returns `false`.
* @returns {boolean} Returns `false`.
*/
public function isAlias() {
return false;
@@ -231,7 +231,7 @@ class Entry {
* Checks if the entry is a constructor.
*
* @memberOf Entry
* @returns {Boolean} Returns `true` if a constructor, else `false`.
* @returns {boolean} Returns `true` if a constructor, else `false`.
*/
public function isCtor() {
if (!isset($this->_isCtor)) {
@@ -244,7 +244,7 @@ class Entry {
* Checks if the entry is a license.
*
* @memberOf Entry
* @returns {Boolean} Returns `true` if a license, else `false`.
* @returns {boolean} Returns `true` if a license, else `false`.
*/
public function isLicense() {
if (!isset($this->_isLicense)) {
@@ -257,7 +257,7 @@ class Entry {
* 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() {
if (!isset($this->_isPlugin)) {
@@ -270,7 +270,7 @@ class Entry {
* 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() {
if (!isset($this->_isPrivate)) {
@@ -283,7 +283,7 @@ class Entry {
* 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)) {
@@ -315,7 +315,7 @@ class Entry {
* Resolves the entry's line number.
*
* @memberOf Entry
* @returns {Number} The entry's line number.
* @returns {number} The entry's line number.
*/
public function getLineNumber() {
if (!isset($this->_lineNumber)) {
@@ -329,8 +329,8 @@ class Entry {
* Extracts the entry's `member` data.
*
* @memberOf Entry
* @param {Number} $index The index of the array value to return.
* @returns {Array|String} The entry's `member` data.
* @param {number} $index The index of the array value to return.
* @returns {(array|string)} The entry's `member` data.
*/
public function getMembers( $index = null ) {
if (!isset($this->_members)) {
@@ -351,7 +351,7 @@ class Entry {
* Extracts the entry's `name` data.
*
* @memberOf Entry
* @returns {String} The entry's `name` data.
* @returns {string} The entry's `name` data.
*/
public function getName() {
if (isset($this->_name)) {
@@ -372,23 +372,26 @@ class Entry {
* Extracts the entry's `param` data.
*
* @memberOf Entry
* @param {Number} $index The index of the array value to return.
* @returns {Array} The entry's `param` data.
* @param {number} $index The index of the array value to return.
* @returns {array} The entry's `param` data.
*/
public function getParams( $index = null ) {
if (!isset($this->_params)) {
preg_match_all('#\*[\t ]*@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();
preg_match_all('#\*[\t ]*@param\s+\{\(?([^})]+)\)?\}\s+(\[.+\]|[$\w|]+(?:\[.+\])?)\s+([\s\S]*?)(?=\*\s\@[a-z]|\*/)#i', $this->entry, $matchTuples);
$matchTuples = array_filter(array_slice($matchTuples, 1));
$result = array();
if (count($matchTuples)) {
foreach ($matchTuples as $tupleKey => $tuple) {
foreach ($tuple as $key => $value) {
if (!isset($result[$key])) {
$result[$key] = array();
}
$result[0][$key][] = trim(preg_replace('/(?:^|\n)[\t ]*\*[\t ]*/', ' ', $value));
$result[$key][] = $tupleKey
? trim(preg_replace('/(?:^|\n)[\t ]*\*[\t ]*/', ' ', $value))
: trim($value);
}
}
$result = $result[0];
}
$this->_params = $result;
}
@@ -401,7 +404,7 @@ class Entry {
* Extracts the entry's `returns` data.
*
* @memberOf Entry
* @returns {String} The entry's `returns` data.
* @returns {string} The entry's `returns` data.
*/
public function getReturns() {
if (isset($this->_returns)) {
@@ -422,18 +425,18 @@ class Entry {
* Extracts the entry's `type` data.
*
* @memberOf Entry
* @returns {String} The entry's `type` data.
* @returns {string} The entry's `type` data.
*/
public function getType() {
if (isset($this->_type)) {
return $this->_type;
}
preg_match('#\*[\t ]*@type\s+(.+)#', $this->entry, $result);
preg_match('#\*[\t ]*@type\s(?:\{\(?)?([^)}\n]+)#', $this->entry, $result);
if (count($result)) {
$result = trim(preg_replace('/(?:^|\n)[\t ]*\*[\t ]?/', ' ', $result[1]));
$result = trim(strtolower($result[1]));
} else {
$result = $this->isFunction() ? 'Function' : 'Unknown';
$result = $this->isFunction() ? 'function' : 'unknown';
}
$this->_type = $result;
return $result;

58
vendor/docdown/src/DocDown/MarkdownGenerator.php vendored
View File

@@ -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;