Doc comment highlighting

components.json

@@ -375,11 +375,37 @@
 			"require": "clike",
 			"owner": "sherblot"
 		},
+		"javadoc": {
+			"title": "JavaDoc",
+			"require": ["java", "javadoclike"],
+			"peerDependencies": [
+				"scala"
+			],
+			"owner": "RunDevelopment"
+		},
+		"javadoclike": {
+			"title": "JavaDoc-like",
+			"peerDependencies": [
+				"java",
+				"javascript",
+				"php"
+			],
+			"owner": "RunDevelopment"
+		},
 		"jolie": {
 			"title": "Jolie",
 			"require": "clike",
 			"owner": "thesave"
 		},
+		"jsdoc": {
+			"title": "JSDoc",
+			"require": ["javascript", "javadoclike"],
+			"peerDependencies": [
+				"actionscript",
+				"coffeescript"
+			],
+			"owner": "RunDevelopment"
+		},
 		"json": {
 			"title": "JSON",
 			"alias": "jsonp",
@@ -464,6 +490,9 @@
 		"n4js": {
 			"title": "N4JS",
 			"require": "javascript",
+			"peerDependencies": [
+				"jsdoc"
+			],
 			"alias": "n4jsd",
 			"owner": "bsmith-n4"
 		},
@@ -537,6 +566,11 @@
 			"require": ["clike", "markup-templating"],
 			"owner": "milesj"
 		},
+		"phpdoc": {
+			"title": "PHPDoc",
+			"require": ["php", "javadoclike"],
+			"owner": "RunDevelopment"
+		},
 		"php-extras": {
 			"title": "PHP Extras",
 			"require": "php",
@@ -623,6 +657,9 @@
 		"jsx": {
 			"title": "React JSX",
 			"require": ["markup", "javascript"],
+			"peerDependencies": [
+				"jsdoc"
+			],
 			"owner": "vkbansal"
 		},
 		"tsx": {

components/prism-javadoc.js

@@ -0,0 +1,56 @@
+(function (Prism) {
+
+	var javaDocLike = Prism.languages.javadoclike;
+	var java = Prism.languages.java;
+
+	var codeLines = {
+		'code': {
+			pattern: /(^(\s*(?:\*\s*)*)).*[^*\s].+$/m,
+			lookbehind: true,
+			inside: java,
+			alias: 'language-java'
+		}
+	};
+
+	Prism.languages.javadoc = Prism.languages.extend('javadoclike', {});
+	Prism.languages.insertBefore('javadoc', 'keyword', {
+		'class-name': [
+			{
+				pattern: /(@(?:exception|throws|see|link|linkplain|value)\s+(?:[a-z\d]+\.)*)[A-Z](?:\w*[a-z]\w*)?(?:\.[A-Z](?:\w*[a-z]\w*)?)*/,
+				lookbehind: true,
+				inside: {
+					'punctuation': /\./
+				}
+			},
+			{
+				pattern: /(@param\s+)<[A-Z]\w*>/,
+				lookbehind: true,
+				inside: {
+					'punctuation': /[.<>]/
+				}
+			}
+		],
+		'namespace': {
+			pattern: /(@(?:exception|throws|see|link|linkplain)\s+)(?:[a-z\d]+\.)+/,
+			lookbehind: true,
+			inside: {
+				'punctuation': /\./
+			}
+		},
+		'code-section': [
+			{
+				pattern: /(\{@code\s+)(?:[^{}]|\{[^{}]*\})+?(?=\s*\})/,
+				lookbehind: true,
+				inside: codeLines
+			},
+			{
+				pattern: /(<(code|tt)>\s*)[\s\S]+?(?=\s*<\/\2>)/,
+				lookbehind: true,
+				inside: codeLines
+			}
+		],
+		'tag': /<\/?(?!\d)[^\s>\/=$<%]+(?:\s+[^\s>\/=]+(?:=(?:("|')(?:\\[\s\S]|(?!\1)[^\\])*\1|[^\s'">=]+))?)*\s*\/?>/i,
+	});
+
+	javaDocLike.addSupport(['java'], Prism.languages.javadoc);
+}(Prism));

components/prism-javadoclike.js

@@ -0,0 +1,78 @@
+(function (Prism) {
+
+	var javaDocLike = Prism.languages.javadoclike = {
+		'parameter': {
+			pattern: /(^\s*(?:\/{3}|\*|\/\*\*)\s*@(?:param|arg|arguments)\s+)\w+/m,
+			lookbehind: true
+		},
+		'keyword': {
+			// keywords are the first word in a line preceded be an `@` or surrounded by curly braces.
+			// @word, {@word}
+			pattern: /(^\s*(?:\/{3}|\*|\/\*\*)\s*|\{)@[a-z][a-zA-Z-]+\b/m,
+			lookbehind: true
+		},
+		'punctuation': /[{}]/
+	};
+
+
+	/**
+	 * Adds doc comment support to the given language and calls a given callback on each doc comment pattern.
+	 *
+	 * @param {string} lang the language add doc comment support to.
+	 * @param {(pattern: {inside: {rest: undefined}}) => void} callback the function called with each doc comment pattern as argument.
+	 */
+	function docCommentSupport(lang, callback) {
+		var tokenName = 'doc-comment';
+
+		var grammar = Prism.languages[lang];
+		if (!grammar) return;
+
+		var token = grammar[tokenName];
+
+		if (!token) {
+			// add doc comment: /** */
+			var definition = {};
+			definition[tokenName] = {
+				pattern: /(^|[^\\])\/\*\*[\s\S]*?(?:\*\/|$)/,
+				alias: 'comment',
+				inside: {}
+			};
+
+			grammar = Prism.languages.insertBefore(lang, 'comment', definition);
+			token = grammar[tokenName];
+
+		} else if (token instanceof RegExp) { // convert existing regex to object
+			token = grammar[tokenName] = { pattern: token };
+		}
+
+		if (Prism.util.type(token) === 'Array') {
+			for (var i = 0, l = token.length; i < l; i++) {
+				if (token[i] instanceof RegExp)
+					token[i] = { pattern: token[i] };
+				callback(token[i]);
+			}
+		} else {
+			callback(token);
+		}
+	}
+
+	Object.defineProperty(javaDocLike, 'addSupport', {
+
+		/**
+		 * Adds doc-comment support to the given languages for the given documentation language.
+		 */
+		value: function addSupport(languages, docLanguage) {
+			languages.forEach(function (lang) {
+				docCommentSupport(lang, function (pattern) {
+					if (!pattern.inside)
+						pattern.inside = {};
+					pattern.inside.rest = docLanguage;
+				});
+			});
+		}
+
+	});
+
+	javaDocLike.addSupport(['java', 'javascript', 'php'], javaDocLike);
+
+}(Prism));

components/prism-jsdoc.js

@@ -0,0 +1,57 @@
+(function (Prism) {
+
+	var javaDocLike = Prism.languages.javadoclike;
+	var javascript = Prism.languages.javascript;
+
+	var type = /\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})+\}/.source;
+
+	Prism.languages.jsdoc = Prism.languages.extend('javadoclike', {
+		'parameter': {
+			pattern: /(@(?:param|arg|argument)\s+(?:\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})+\}\s+)?)(?:\w+|\[\w+(?:=[^[[\]]+)?\])(?=\s|$)/,
+			lookbehind: true,
+			inside: {
+				'code': {
+					pattern: /(\w=)[^[[\]]+(?=\]$)/,
+					lookbehind: true,
+					inside: javascript,
+					alias: 'language-javascript'
+				},
+				'punctuation': /[=[\]]/
+			}
+		}
+	});
+
+	Prism.languages.insertBefore('jsdoc', 'keyword', {
+		'class-name': [
+			{
+				pattern: /(@[a-z]+\s+)\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})+\}/,
+				lookbehind: true,
+				inside: {
+					'punctuation': /[.,:?=<>|{}()[\]]/
+				}
+			},
+			{
+				pattern: /(@(?:augments|extends|class|interface|memberof!?|this)\s+)[A-Z]\w*(?:\.[A-Z]\w*)*/,
+				lookbehind: true,
+				inside: {
+					'punctuation': /\./
+				}
+			}
+		],
+		'example': {
+			pattern: /(@example\s+)[^@]+?(?=\s*(?:\*\s*)?(?:@\w|\*\/))/,
+			lookbehind: true,
+			inside: {
+				'code': {
+					pattern: /^(\s*(?:\*\s*)?).+$/m,
+					lookbehind: true,
+					inside: javascript,
+					alias: 'language-javascript'
+				}
+			}
+		}
+	});
+
+	javaDocLike.addSupport(['javascript'], Prism.languages.jsdoc);
+
+}(Prism));

components/prism-phpdoc.js

@@ -0,0 +1,28 @@
+(function (Prism) {
+
+	var typeExpression = /(?:[a-zA-Z]\w*|[|\\[\]])+/.source;
+
+	Prism.languages.phpdoc = Prism.languages.extend('javadoclike', {
+		'parameter': {
+			pattern: RegExp('(' + /@(?:global|param|property(?:-read|-write)?|var)\s+/.source + '(?:' + typeExpression + '\\s+)?)' + /\$\w+/.source),
+			lookbehind: true
+		}
+	});
+
+	Prism.languages.insertBefore('phpdoc', 'keyword', {
+		'class-name': [
+			{
+				pattern: RegExp(/(@(?:global|package|param|property(?:-read|-write)?|return|subpackage|throws|var)\s+)/.source + typeExpression),
+				lookbehind: true,
+				inside: {
+					'keyword': /\b(?:callback|resource|boolean|integer|double|object|string|array|false|float|mixed|bool|null|self|true|void|int)\b/,
+					'punctuation': /[|\\[\]()]/
+				}
+			}
+		],
+	});
+
+	var javaDocLike = Prism.languages.javadoclike;
+	javaDocLike.addSupport(['php'], Prism.languages.phpdoc);
+
+}(Prism));

plugins/autoloader/prism-autoloader.js

@@ -4,7 +4,7 @@
 	}
 
 	// The dependencies map is built automatically with gulp
-	var lang_dependencies = /*languages_placeholder[*/{"javascript":"clike","actionscript":"javascript","arduino":"cpp","aspnet":["markup","csharp"],"bison":"c","c":"clike","csharp":"clike","cpp":"c","coffeescript":"javascript","crystal":"ruby","css-extras":"css","d":"clike","dart":"clike","django":"markup","erb":["ruby","markup-templating"],"fsharp":"clike","flow":"javascript","glsl":"clike","gml":"clike","go":"clike","groovy":"clike","haml":"ruby","handlebars":"markup-templating","haxe":"clike","java":"clike","jolie":"clike","kotlin":"clike","less":"css","markdown":"markup","markup-templating":"markup","n4js":"javascript","nginx":"clike","objectivec":"c","opencl":"cpp","parser":"markup","php":["clike","markup-templating"],"php-extras":"php","plsql":"sql","processing":"clike","protobuf":"clike","pug":"javascript","qore":"clike","jsx":["markup","javascript"],"tsx":["jsx","typescript"],"reason":"clike","ruby":"clike","sass":"css","scss":"css","scala":"java","smarty":"markup-templating","soy":"markup-templating","swift":"clike","tap":"yaml","textile":"markup","tt2":["clike","markup-templating"],"twig":"markup","typescript":"javascript","vbnet":"basic","velocity":"markup","wiki":"markup","xeora":"markup","xquery":"markup"}/*]*/;
+	var lang_dependencies = /*languages_placeholder[*/{"javascript":"clike","actionscript":"javascript","arduino":"cpp","aspnet":["markup","csharp"],"bison":"c","c":"clike","csharp":"clike","cpp":"c","coffeescript":"javascript","crystal":"ruby","css-extras":"css","d":"clike","dart":"clike","django":"markup","erb":["ruby","markup-templating"],"fsharp":"clike","flow":"javascript","glsl":"clike","gml":"clike","go":"clike","groovy":"clike","haml":"ruby","handlebars":"markup-templating","haxe":"clike","java":"clike","javadoc":["java","javadoclike"],"jolie":"clike","jsdoc":["javascript","javadoclike"],"kotlin":"clike","less":"css","markdown":"markup","markup-templating":"markup","n4js":"javascript","nginx":"clike","objectivec":"c","opencl":"cpp","parser":"markup","php":["clike","markup-templating"],"phpdoc":["php","javadoclike"],"php-extras":"php","plsql":"sql","processing":"clike","protobuf":"clike","pug":"javascript","qore":"clike","jsx":["markup","javascript"],"tsx":["jsx","typescript"],"reason":"clike","ruby":"clike","sass":"css","scss":"css","scala":"java","smarty":"markup-templating","soy":"markup-templating","swift":"clike","tap":"yaml","textile":"markup","tt2":["clike","markup-templating"],"twig":"markup","typescript":"javascript","vbnet":"basic","velocity":"markup","wiki":"markup","xeora":"markup","xquery":"markup"}/*]*/;
 
 	var lang_data = {};