Skip to content

Commit 493d19e

Browse files
RunDevelopmentRunDevelopment
authored
Added doc comment highlighting (#1541)
This adds support for JavaDoc, JSDoc, TSDoc, and PHPDoc.
1 parent bb62860 commit 493d19e

29 files changed

+1246
-6
lines changed

‎components.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎components.json‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -403,6 +403,23 @@
403403
"require": "clike",
404404
"owner": "sherblot"
405405
},
406+
"javadoc": {
407+
"title": "JavaDoc",
408+
"require": ["markup", "java", "javadoclike"],
409+
"peerDependencies": [
410+
"scala"
411+
],
412+
"owner": "RunDevelopment"
413+
},
414+
"javadoclike": {
415+
"title": "JavaDoc-like",
416+
"peerDependencies": [
417+
"java",
418+
"javascript",
419+
"php"
420+
],
421+
"owner": "RunDevelopment"
422+
},
406423
"javastacktrace": {
407424
"title": "Java stack trace",
408425
"owner": "RunDevelopment"
@@ -412,6 +429,15 @@
412429
"require": "clike",
413430
"owner": "thesave"
414431
},
432+
"jsdoc": {
433+
"title": "JSDoc",
434+
"require": ["javascript", "javadoclike"],
435+
"peerDependencies": [
436+
"actionscript",
437+
"coffeescript"
438+
],
439+
"owner": "RunDevelopment"
440+
},
415441
"js-extras": {
416442
"title": "JS Extras",
417443
"require": "javascript",
@@ -518,6 +544,9 @@
518544
"n4js": {
519545
"title": "N4JS",
520546
"require": "javascript",
547+
"peerDependencies": [
548+
"jsdoc"
549+
],
521550
"alias": "n4jsd",
522551
"owner": "bsmith-n4"
523552
},
@@ -595,6 +624,11 @@
595624
"require": ["clike", "markup-templating"],
596625
"owner": "milesj"
597626
},
627+
"phpdoc": {
628+
"title": "PHPDoc",
629+
"require": ["php", "javadoclike"],
630+
"owner": "RunDevelopment"
631+
},
598632
"php-extras": {
599633
"title": "PHP Extras",
600634
"require": "php",
@@ -681,7 +715,10 @@
681715
"jsx": {
682716
"title": "React JSX",
683717
"require": ["markup", "javascript"],
684-
"peerDependencies": "js-extras",
718+
"peerDependencies": [
719+
"jsdoc",
720+
"js-extras"
721+
],
685722
"owner": "vkbansal"
686723
},
687724
"tsx": {

‎components/prism-javadoc.js‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
(function (Prism) {
2+
3+
var codeLines = {
4+
'code': {
5+
pattern: /(^(\s*(?:\*\s*)*)).*[^*\s].+$/m,
6+
lookbehind: true,
7+
inside: Prism.languages.java,
8+
alias: 'language-java'
9+
}
10+
};
11+
12+
Prism.languages.javadoc = Prism.languages.extend('javadoclike', {});
13+
Prism.languages.insertBefore('javadoc', 'keyword', {
14+
'class-name': [
15+
{
16+
pattern: /(@(?:exception|throws|see|link|linkplain|value)\s+(?:[a-z\d]+\.)*)[A-Z](?:\w*[a-z]\w*)?(?:\.[A-Z](?:\w*[a-z]\w*)?)*/,
17+
lookbehind: true,
18+
inside: {
19+
'punctuation': /\./
20+
}
21+
},
22+
{
23+
// @param <T> the first generic type parameter
24+
pattern: /(@param\s+)<[A-Z]\w*>/,
25+
lookbehind: true,
26+
inside: {
27+
'punctuation': /[.<>]/
28+
}
29+
}
30+
],
31+
'namespace': {
32+
pattern: /(@(?:exception|throws|see|link|linkplain)\s+)(?:[a-z\d]+\.)+/,
33+
lookbehind: true,
34+
inside: {
35+
'punctuation': /\./
36+
}
37+
},
38+
'code-section': [
39+
{
40+
pattern: /(\{@code\s+)(?:[^{}]|\{[^{}]*\})+?(?=\s*\})/,
41+
lookbehind: true,
42+
inside: codeLines
43+
},
44+
{
45+
pattern: /(<(code|tt)>\s*)[\s\S]+?(?=\s*<\/\2>)/,
46+
lookbehind: true,
47+
inside: codeLines
48+
}
49+
],
50+
'tag': Prism.languages.markup.tag,
51+
});
52+
53+
Prism.languages.javadoclike.addSupport('java', Prism.languages.javadoc);
54+
}(Prism));

‎components/prism-javadoc.min.js‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎components/prism-javadoclike.js‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
(function (Prism) {
2+
3+
var javaDocLike = Prism.languages.javadoclike = {
4+
'parameter': {
5+
pattern: /(^\s*(?:\/{3}|\*|\/\*\*)\s*@(?:param|arg|arguments)\s+)\w+/m,
6+
lookbehind: true
7+
},
8+
'keyword': {
9+
// keywords are the first word in a line preceded be an `@` or surrounded by curly braces.
10+
// @word, {@word}
11+
pattern: /(^\s*(?:\/{3}|\*|\/\*\*)\s*|\{)@[a-z][a-zA-Z-]+\b/m,
12+
lookbehind: true
13+
},
14+
'punctuation': /[{}]/
15+
};
16+
17+
18+
/**
19+
* Adds doc comment support to the given language and calls a given callback on each doc comment pattern.
20+
*
21+
* @param {string} lang the language add doc comment support to.
22+
* @param {(pattern: {inside: {rest: undefined}}) => void} callback the function called with each doc comment pattern as argument.
23+
*/
24+
function docCommentSupport(lang, callback) {
25+
var tokenName = 'doc-comment';
26+
27+
var grammar = Prism.languages[lang];
28+
if (!grammar) {
29+
return;
30+
}
31+
var token = grammar[tokenName];
32+
33+
if (!token) {
34+
// add doc comment: /** */
35+
var definition = {};
36+
definition[tokenName] = {
37+
pattern: /(^|[^\\])\/\*\*[^/][\s\S]*?(?:\*\/|$)/,
38+
alias: 'comment'
39+
};
40+
41+
grammar = Prism.languages.insertBefore(lang, 'comment', definition);
42+
token = grammar[tokenName];
43+
}
44+
45+
if (token instanceof RegExp) { // convert regex to object
46+
token = grammar[tokenName] = { pattern: token };
47+
}
48+
49+
if (Prism.util.type(token) === 'Array') {
50+
for (var i = 0, l = token.length; i < l; i++) {
51+
if (token[i] instanceof RegExp) {
52+
token[i] = { pattern: token[i] };
53+
}
54+
callback(token[i]);
55+
}
56+
} else {
57+
callback(token);
58+
}
59+
}
60+
61+
/**
62+
* Adds doc-comment support to the given languages for the given documentation language.
63+
*
64+
* @param {string[]|string} languages
65+
* @param {Object} docLanguage
66+
*/
67+
function addSupport(languages, docLanguage) {
68+
if (typeof languages === 'string') {
69+
languages = [languages];
70+
}
71+
72+
languages.forEach(function (lang) {
73+
docCommentSupport(lang, function (pattern) {
74+
if (!pattern.inside) {
75+
pattern.inside = {};
76+
}
77+
pattern.inside.rest = docLanguage;
78+
});
79+
});
80+
}
81+
82+
Object.defineProperty(javaDocLike, 'addSupport', { value: addSupport });
83+
84+
javaDocLike.addSupport(['java', 'javascript', 'php'], javaDocLike);
85+
86+
}(Prism));

‎components/prism-javadoclike.min.js‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎components/prism-jsdoc.js‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
(function (Prism) {
2+
3+
var javascript = Prism.languages.javascript;
4+
5+
var type = /{(?:[^{}]|{(?:[^{}]|{[^{}]*})*})+}/.source;
6+
var parameterPrefix = '(@(?:param|arg|argument|property)\\s+(?:' + type + '\\s+)?)';
7+
8+
Prism.languages.jsdoc = Prism.languages.extend('javadoclike', {
9+
'parameter': {
10+
// @param {string} foo - foo bar
11+
pattern: RegExp(parameterPrefix + /[$\w\xA0-\uFFFF.]+(?=\s|$)/.source),
12+
lookbehind: true,
13+
inside: {
14+
'punctuation': /\./
15+
}
16+
}
17+
});
18+
19+
Prism.languages.insertBefore('jsdoc', 'keyword', {
20+
'optional-parameter': {
21+
// @param {string} [baz.foo="bar"] foo bar
22+
pattern: RegExp(parameterPrefix + /\[[$\w\xA0-\uFFFF.]+(?:=[^[\]]+)?\](?=\s|$)/.source),
23+
lookbehind: true,
24+
inside: {
25+
'parameter': {
26+
pattern: /(^\[)[$\w\xA0-\uFFFF\.]+/,
27+
lookbehind: true,
28+
inside: {
29+
'punctuation': /\./
30+
}
31+
},
32+
'code': {
33+
pattern: /(=)[\s\S]*(?=\]$)/,
34+
lookbehind: true,
35+
inside: javascript,
36+
alias: 'language-javascript'
37+
},
38+
'punctuation': /[=[\]]/
39+
}
40+
},
41+
'class-name': [
42+
{
43+
pattern: RegExp('(@[a-z]+\\s+)' + type),
44+
lookbehind: true,
45+
inside: {
46+
'punctuation': /[.,:?=<>|{}()[\]]/
47+
}
48+
},
49+
{
50+
pattern: /(@(?:augments|extends|class|interface|memberof!?|this)\s+)[A-Z]\w*(?:\.[A-Z]\w*)*/,
51+
lookbehind: true,
52+
inside: {
53+
'punctuation': /\./
54+
}
55+
}
56+
],
57+
'example': {
58+
pattern: /(@example\s+)[^@]+?(?=\s*(?:\*\s*)?(?:@\w|\*\/))/,
59+
lookbehind: true,
60+
inside: {
61+
'code': {
62+
pattern: /^(\s*(?:\*\s*)?).+$/m,
63+
lookbehind: true,
64+
inside: javascript,
65+
alias: 'language-javascript'
66+
}
67+
}
68+
}
69+
});
70+
71+
Prism.languages.javadoclike.addSupport('javascript', Prism.languages.jsdoc);
72+
73+
}(Prism));

‎components/prism-jsdoc.min.js‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎components/prism-phpdoc.js‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
(function (Prism) {
2+
3+
var typeExpression = /(?:[a-zA-Z]\w*|[|\\[\]])+/.source;
4+
5+
Prism.languages.phpdoc = Prism.languages.extend('javadoclike', {
6+
'parameter': {
7+
pattern: RegExp('(@(?:global|param|property(?:-read|-write)?|var)\\s+(?:' + typeExpression + '\\s+)?)\\$\\w+'),
8+
lookbehind: true
9+
}
10+
});
11+
12+
Prism.languages.insertBefore('phpdoc', 'keyword', {
13+
'class-name': [
14+
{
15+
pattern: RegExp('(@(?:global|package|param|property(?:-read|-write)?|return|subpackage|throws|var)\\s+)' + typeExpression),
16+
lookbehind: true,
17+
inside: {
18+
'keyword': /\b(?:callback|resource|boolean|integer|double|object|string|array|false|float|mixed|bool|null|self|true|void|int)\b/,
19+
'punctuation': /[|\\[\]()]/
20+
}
21+
}
22+
],
23+
});
24+
25+
Prism.languages.javadoclike.addSupport('php', Prism.languages.phpdoc);
26+
27+
}(Prism));

‎components/prism-phpdoc.min.js‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)