Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit f4c4385

Browse files
dcodeIOdcodeIO
authored
docs: Share JSDoc patch with API docs (#2252)
1 parent a799376 commit f4c4385

5 files changed

Lines changed: 104 additions & 71 deletions

File tree

‎cli/lib/tsd-jsdoc/patch.js‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
"use strict";
2+
3+
var typeParserPatched = false;
4+
var typeLinkerPatched = false;
5+
var typeScriptTypePattern = /[&;]|\?:|=>|\bkeyof\b|\btypeof\b/;
6+
7+
function normalizeType(type) {
8+
return type.replace(/\r?\n|\r/g, "\n");
9+
}
10+
11+
function patchTypeExpressionParser(dictionary) {
12+
var type = require("jsdoc/tag/type");
13+
var parse = type.parse,
14+
typeTag = dictionary.lookUp("type");
15+
16+
if (typeTag && !typeTag.protobufjsPatched) {
17+
typeTag.onTagText = function onTypeTagText(text) {
18+
var openIdx = text.indexOf("{"),
19+
closeIdx = text.indexOf("}");
20+
21+
if (openIdx !== 0 || closeIdx <= openIdx + 1)
22+
text = "{" + text + "}";
23+
24+
return text;
25+
};
26+
typeTag.protobufjsPatched = true;
27+
}
28+
29+
if (typeParserPatched)
30+
return;
31+
typeParserPatched = true;
32+
33+
type.parse = function parseTypeScriptType(tagValue, canHaveName, canHaveType) {
34+
try {
35+
return parse(tagValue, canHaveName, canHaveType);
36+
} catch (e) {
37+
if (!canHaveType)
38+
throw e;
39+
40+
var text = String(tagValue || "");
41+
var open = text.indexOf("{");
42+
if (open < 0)
43+
throw e;
44+
45+
var depth = 0;
46+
var close = -1;
47+
for (var i = open; i < text.length; ++i) {
48+
var ch = text.charAt(i);
49+
if (ch === "{")
50+
++depth;
51+
else if (ch === "}" && --depth === 0) {
52+
close = i;
53+
break;
54+
}
55+
}
56+
if (close < 0)
57+
throw e;
58+
59+
var expression = normalizeType(text.substring(open + 1, close)).trim();
60+
if (!typeScriptTypePattern.test(expression) && !/^\s*\{/.test(expression))
61+
throw e;
62+
63+
var name = canHaveName ? text.substring(close + 1).trim() : "";
64+
return {
65+
type: [ expression ],
66+
typeExpression: expression,
67+
name: name
68+
};
69+
}
70+
};
71+
}
72+
73+
function patchTypeExpressionLinks() {
74+
if (typeLinkerPatched)
75+
return;
76+
typeLinkerPatched = true;
77+
78+
var helper = require("jsdoc/util/templateHelper");
79+
var linkto = helper.linkto;
80+
81+
helper.linkto = function linkTypeScriptType(longname, linkText, cssClass, fragmentId) {
82+
var stripped = longname ? String(longname).replace(/^<|>$/g, "") : "";
83+
if (stripped && typeScriptTypePattern.test(stripped) &&
84+
!/^(http|ftp)s?:\/\//.test(stripped) &&
85+
/\{@.+\}/.test(stripped) === false &&
86+
/^<[\s\S]+>/.test(stripped) === false)
87+
return linkText || helper.htmlsafe(longname);
88+
89+
return linkto.call(this, longname, linkText, cssClass, fragmentId);
90+
};
91+
}
92+
93+
exports.normalizeType = normalizeType;
94+
95+
exports.defineTags = function(dictionary) {
96+
patchTypeExpressionParser(dictionary);
97+
patchTypeExpressionLinks();
98+
};

‎cli/lib/tsd-jsdoc/plugin.js‎

Lines changed: 3 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,9 @@
11
"use strict";
22

3-
var typeParserPatched = false;
4-
5-
function normalizeType(type) {
6-
return type.replace(/\r?\n|\r/g, "\n");
7-
}
8-
9-
function patchTypeScriptTypes(dictionary) {
10-
var type = require("jsdoc/tag/type");
11-
var parse = type.parse,
12-
typeTag = dictionary.lookUp("type");
13-
14-
if (typeTag && !typeTag.protobufjsPatched) {
15-
typeTag.onTagText = function onTypeTagText(text) {
16-
var openIdx = text.indexOf("{"),
17-
closeIdx = text.indexOf("}");
18-
19-
if (openIdx !== 0 || closeIdx <= openIdx + 1)
20-
text = "{" + text + "}";
21-
22-
return text;
23-
};
24-
typeTag.protobufjsPatched = true;
25-
}
26-
27-
if (typeParserPatched)
28-
return;
29-
typeParserPatched = true;
30-
31-
type.parse = function parseTypeScriptType(tagValue, canHaveName, canHaveType) {
32-
try {
33-
return parse(tagValue, canHaveName, canHaveType);
34-
} catch (e) {
35-
if (!canHaveType)
36-
throw e;
37-
38-
var text = String(tagValue || "");
39-
var open = text.indexOf("{");
40-
if (open < 0)
41-
throw e;
42-
43-
var depth = 0;
44-
var close = -1;
45-
for (var i = open; i < text.length; ++i) {
46-
var ch = text.charAt(i);
47-
if (ch === "{")
48-
++depth;
49-
else if (ch === "}" && --depth === 0) {
50-
close = i;
51-
break;
52-
}
53-
}
54-
if (close < 0)
55-
throw e;
56-
57-
var expression = normalizeType(text.substring(open + 1, close)).trim();
58-
if (!/[&;]|\?:|=>|\bkeyof\b|\btypeof\b|^\s*\{/.test(expression))
59-
throw e;
60-
61-
var name = canHaveName ? text.substring(close + 1).trim() : "";
62-
return {
63-
type: [ expression ],
64-
typeExpression: expression,
65-
name: name
66-
};
67-
}
68-
};
69-
}
3+
var patch = require("./patch");
704

715
exports.defineTags = function(dictionary) {
72-
patchTypeScriptTypes(dictionary);
6+
patch.defineTags(dictionary);
737

748
dictionary.defineTag("template", {
759
mustHaveValue: true,
@@ -85,7 +19,7 @@ exports.defineTags = function(dictionary) {
8519
canHaveType: false,
8620
canHaveName: false,
8721
onTagged: function(doclet, tag) {
88-
doclet.tsType = normalizeType(tag.text);
22+
doclet.tsType = patch.normalizeType(tag.text);
8923
}
9024
});
9125
};

‎config/jsdoc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
"excludePattern": "(^|\\/|\\\\)_"
1212
},
1313
"plugins": [
14+
"./cli/lib/tsd-jsdoc/patch",
1415
"./node_modules/jsdoc/plugins/markdown"
1516
],
1617
"templates": {

‎lib/jsdoc-template‎

‎src/util/pool.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ module.exports = pool;
1616
* @param {number} start Start offset
1717
* @param {number} end End offset
1818
* @returns {Uint8Array} Buffer slice
19-
* @this {Uint8Array}
19+
* @this Uint8Array
2020
*/
2121

2222
/**

0 commit comments

Comments
 (0)