From 3072181e63aeb3323fa71342bd9fd845954a278a Mon Sep 17 00:00:00 2001
From: Michael Schmidt <mitchi5000.ms@googlemail.com>
Date: Wed, 6 May 2020 10:06:01 +0200
Subject: [PATCH] JavaDoc: Improvements (#2324)

This makes some improvements to JavaDoc:

- Extended support for [references](https://corochann.com/javadoc-coding-rule-of-link-linkplain-see-372.html).
- Better code support
    - Added support for `<pre>` elements
    - Added support for HTML inside code (but not `{@code}` code)
    - Fixed that the line splitting pattern required at least 2 characters per line
- Added support for HTML entities.
- Changed the line ends to `\r\n` for all test files.
---
 components/prism-javadoc.js                   |  90 ++-
 components/prism-javadoc.min.js               |   2 +-
 .../languages/javadoc/class-name_feature.test |  40 -
 tests/languages/javadoc/code_feature.test     | 695 ++++++++++++++----
 tests/languages/javadoc/entity_feature.test   |  15 +
 tests/languages/javadoc/keyword_feature.test  | 152 ++--
 .../languages/javadoc/parameter_feature.test  |  40 +-
 .../languages/javadoc/reference_feature.test  | 348 +++++++++
 tests/languages/javadoc/tag_feature.test      | 238 +++---
 9 files changed, 1207 insertions(+), 413 deletions(-)
 delete mode 100644 tests/languages/javadoc/class-name_feature.test
 create mode 100644 tests/languages/javadoc/entity_feature.test
 create mode 100644 tests/languages/javadoc/reference_feature.test

diff --git a/components/prism-javadoc.js b/components/prism-javadoc.js
index 052ceaf3fa..de38724ece 100644
--- a/components/prism-javadoc.js
+++ b/components/prism-javadoc.js
@@ -1,53 +1,81 @@
 (function (Prism) {
 
-	var codeLines = {
-		'code': {
-			pattern: /(^(?:\s*(?:\*\s*)*)).*[^*\s].+$/m,
-			lookbehind: true,
-			inside: Prism.languages.java,
-			alias: 'language-java'
-		}
-	};
+	var codeLinePattern = /(^(?:\s*(?:\*\s*)*)).*[^*\s].*$/m;
+
+	var memberReference = /#\s*\w+(?:\s*\([^()]*\))?/.source;
+	var reference = /(?:[a-zA-Z]\w+\s*\.\s*)*[A-Z]\w*(?:\s*<mem>)?|<mem>/.source.replace(/<mem>/g, function () { return memberReference });
 
 	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': /\./
-				}
-			},
-			{
-				// @param <T> the first generic type parameter
-				pattern: /(@param\s+)<[A-Z]\w*>/,
-				lookbehind: true,
-				inside: {
-					'punctuation': /[.<>]/
-				}
+		'reference': {
+			pattern: RegExp(/(@(?:exception|throws|see|link|linkplain|value)\s+(?:\*\s*)?)/.source + '(?:' + reference + ')'),
+			lookbehind: true,
+			inside: {
+				'function': {
+					pattern: /(#\s*)\w+(?=\s*\()/,
+					lookbehind: true
+				},
+				'field': {
+					pattern: /(#\s*)\w+/,
+					lookbehind: true
+				},
+				'namespace': {
+					pattern: /\b(?:[a-z]\w*\s*\.\s*)+/,
+					inside: {
+						'punctuation': /\./
+					}
+				},
+				'class-name': /\b[A-Z]\w*/,
+				'keyword': Prism.languages.java.keyword,
+				'punctuation': /[#()[\],.]/
 			}
-		],
-		'namespace': {
-			pattern: /(@(?:exception|throws|see|link|linkplain)\s+)(?:[a-z\d]+\.)+/,
+		},
+		'class-name': {
+			// @param <T> the first generic type parameter
+			pattern: /(@param\s+)<[A-Z]\w*>/,
 			lookbehind: true,
 			inside: {
-				'punctuation': /\./
+				'punctuation': /[.<>]/
 			}
 		},
 		'code-section': [
 			{
-				pattern: /(\{@code\s+)(?:[^{}]|\{[^{}]*\})+?(?=\s*\})/,
+				pattern: /(\{@code\s+)(?:[^{}]|\{(?:[^{}]|\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\})*\})+?(?=\s*\})/,
 				lookbehind: true,
-				inside: codeLines
+				inside: {
+					'code': {
+						// there can't be any HTML inside of {@code} tags
+						pattern: codeLinePattern,
+						lookbehind: true,
+						inside: Prism.languages.java,
+						alias: 'language-java'
+					}
+				}
 			},
 			{
-				pattern: /(<(code|tt)>\s*)[\s\S]+?(?=\s*<\/\2>)/,
+				pattern: /(<(code|pre|tt)>(?!<code>)\s*)[\s\S]+?(?=\s*<\/\2>)/,
 				lookbehind: true,
-				inside: codeLines
+				inside: {
+					'line': {
+						pattern: codeLinePattern,
+						lookbehind: true,
+						inside: {
+							// highlight HTML tags and entities
+							'tag': Prism.languages.markup.tag,
+							'entity': Prism.languages.markup.entity,
+							'code': {
+								// everything else is Java code
+								pattern: /.+/,
+								inside: Prism.languages.java,
+								alias: 'language-java'
+							}
+						}
+					}
+				}
 			}
 		],
 		'tag': Prism.languages.markup.tag,
+		'entity': Prism.languages.markup.entity,
 	});
 
 	Prism.languages.javadoclike.addSupport('java', Prism.languages.javadoc);
diff --git a/components/prism-javadoc.min.js b/components/prism-javadoc.min.js
index 84726d8702..18d7f9c7e4 100644
--- a/components/prism-javadoc.min.js
+++ b/components/prism-javadoc.min.js
@@ -1 +1 @@
-!function(a){var e={code:{pattern:/(^(?:\s*(?:\*\s*)*)).*[^*\s].+$/m,lookbehind:!0,inside:a.languages.java,alias:"language-java"}};a.languages.javadoc=a.languages.extend("javadoclike",{}),a.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:!0,inside:{punctuation:/\./}},{pattern:/(@param\s+)<[A-Z]\w*>/,lookbehind:!0,inside:{punctuation:/[.<>]/}}],namespace:{pattern:/(@(?:exception|throws|see|link|linkplain)\s+)(?:[a-z\d]+\.)+/,lookbehind:!0,inside:{punctuation:/\./}},"code-section":[{pattern:/(\{@code\s+)(?:[^{}]|\{[^{}]*\})+?(?=\s*\})/,lookbehind:!0,inside:e},{pattern:/(<(code|tt)>\s*)[\s\S]+?(?=\s*<\/\2>)/,lookbehind:!0,inside:e}],tag:a.languages.markup.tag}),a.languages.javadoclike.addSupport("java",a.languages.javadoc)}(Prism);
\ No newline at end of file
+!function(a){var e=/(^(?:\s*(?:\*\s*)*)).*[^*\s].*$/m,n="(?:[a-zA-Z]\\w+\\s*\\.\\s*)*[A-Z]\\w*(?:\\s*<mem>)?|<mem>".replace(/<mem>/g,function(){return"#\\s*\\w+(?:\\s*\\([^()]*\\))?"});a.languages.javadoc=a.languages.extend("javadoclike",{}),a.languages.insertBefore("javadoc","keyword",{reference:{pattern:RegExp("(@(?:exception|throws|see|link|linkplain|value)\\s+(?:\\*\\s*)?)(?:"+n+")"),lookbehind:!0,inside:{function:{pattern:/(#\s*)\w+(?=\s*\()/,lookbehind:!0},field:{pattern:/(#\s*)\w+/,lookbehind:!0},namespace:{pattern:/\b(?:[a-z]\w*\s*\.\s*)+/,inside:{punctuation:/\./}},"class-name":/\b[A-Z]\w*/,keyword:a.languages.java.keyword,punctuation:/[#()[\],.]/}},"class-name":{pattern:/(@param\s+)<[A-Z]\w*>/,lookbehind:!0,inside:{punctuation:/[.<>]/}},"code-section":[{pattern:/(\{@code\s+)(?:[^{}]|\{(?:[^{}]|\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\})*\})+?(?=\s*\})/,lookbehind:!0,inside:{code:{pattern:e,lookbehind:!0,inside:a.languages.java,alias:"language-java"}}},{pattern:/(<(code|pre|tt)>(?!<code>)\s*)[\s\S]+?(?=\s*<\/\2>)/,lookbehind:!0,inside:{line:{pattern:e,lookbehind:!0,inside:{tag:a.languages.markup.tag,entity:a.languages.markup.entity,code:{pattern:/.+/,inside:a.languages.java,alias:"language-java"}}}}}],tag:a.languages.markup.tag,entity:a.languages.markup.entity}),a.languages.javadoclike.addSupport("java",a.languages.javadoc)}(Prism);
\ No newline at end of file
diff --git a/tests/languages/javadoc/class-name_feature.test b/tests/languages/javadoc/class-name_feature.test
deleted file mode 100644
index 20ac38ebd8..0000000000
--- a/tests/languages/javadoc/class-name_feature.test
+++ /dev/null
@@ -1,40 +0,0 @@
-/**
- * @throws IllegalArgumentException if the argument is negative.
- * @see org.my.company.InfoClass for more information.
- * @param <T> the first generic argument.
- */
-
-----------------------------------------------------
-
-[
-	"/**\n * ",
-	["keyword", "@throws"],
-	["class-name", [
-		"IllegalArgumentException"
-	]],
-	" if the argument is negative.\n * ",
-	["keyword", "@see"],
-	["namespace", [
-		"org",
-		["punctuation", "."],
-		"my",
-		["punctuation", "."],
-		"company",
-		["punctuation", "."]
-	]],
-	["class-name", [
-		"InfoClass"
-	]],
-	" for more information.\n * ",
-	["keyword", "@param"],
-	["class-name", [
-		["punctuation", "<"],
-		"T",
-		["punctuation", ">"]
-	]],
-	" the first generic argument.\n */"
-]
-
-----------------------------------------------------
-
-Checks for class names.
diff --git a/tests/languages/javadoc/code_feature.test b/tests/languages/javadoc/code_feature.test
index c9e52394c3..a39babdfee 100644
--- a/tests/languages/javadoc/code_feature.test
+++ b/tests/languages/javadoc/code_feature.test
@@ -1,135 +1,560 @@
-/**
- * {@code this.foo} is never {@code null}.
- * <code>Foo.bar(null)</code>
- * <pre><code>
- * for (int i = 0; i < array.length; i++) {
- *     array[i] += 1;
- * }
- * return array;
- * </code></pre>
- */
-
-----------------------------------------------------
-
-[
-	"/**\n * ",
-	["punctuation", "{"],
-	["keyword", "@code"],
-	["code-section", [
-		["code", [
-			["keyword", "this"],
-			["punctuation", "."],
-			"foo"
-		]]
-	]],
-	["punctuation", "}"],
-	" is never ",
-	["punctuation", "{"],
-	["keyword", "@code"],
-	["code-section", [
-		["code", [
-			["keyword", "null"]
-		]]
-	]],
-	["punctuation", "}"],
-	".\n * ",
-
-	["tag", [
-		["tag", [
-			["punctuation", "<"],
-			"code"
-		]],
-		["punctuation", ">"]
-	]],
-	["code-section", [
-		["code", [
-			["class-name", "Foo"],
-			["punctuation", "."],
-			["function", "bar"],
-			["punctuation", "("],
-			["keyword", "null"],
-			["punctuation", ")"]
-		]]
-	]],
-	["tag", [
-		["tag", [
-			["punctuation", "</"],
-			"code"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n * ",
-
-	["tag", [
-		["tag", [
-			["punctuation", "<"],
-			"pre"
-		]],
-		["punctuation", ">"]
-	]],
-	["tag", [
-		["tag", [
-			["punctuation", "<"],
-			"code"
-		]],
-		["punctuation", ">"]
-	]],
-	["code-section", [
-		"* ",
-		["code", [
-			["keyword", "for"],
-			["punctuation", "("],
-			["keyword", "int"],
-			" i ",
-			["operator", "="],
-			["number", "0"],
-			["punctuation", ";"],
-			" i ",
-			["operator", "<"],
-			" array",
-			["punctuation", "."],
-			"length",
-			["punctuation", ";"],
-			" i",
-			["operator", "++"],
-			["punctuation", ")"],
-			["punctuation", "{"]
-		]],
-		"\n *     ",
-		["code", [
-			"array",
-			["punctuation", "["],
-			"i",
-			["punctuation", "]"],
-			["operator", "+="],
-			["number", "1"],
-			["punctuation", ";"]
-		]],
-		"\n * }\n * ",
-		["code", [
-			["keyword", "return"],
-			" array",
-			["punctuation", ";"]
-		]],
-		"\n *"
-	]],
-	["tag", [
-		["tag", [
-			["punctuation", "</"],
-			"code"
-		]],
-		["punctuation", ">"]
-	]],
-	["tag", [
-		["tag", [
-			["punctuation", "</"],
-			"pre"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n */"
-]
-
-----------------------------------------------------
-
-Checks for code.
+/**
+ * {@code this.foo} is never {@code null}.
+ *
+ * <code>Foo.bar(null)</code>
+ * <tt>Foo</tt>
+ *
+ * <pre><code>
+ * for (int i = 0; i < array.length; i++) {
+ *     array[i] += 1;
+ * }
+ * return array;
+ * </code></pre>
+ *
+ * <pre>{@code
+ *     String message = String.join("-", "Java", "is", "cool");
+ *     // message returned is: "Java-is-cool"
+ * }</pre>
+ *
+ * <pre>
+ *     dstBegin + (srcEnd-srcBegin) - 1
+ * </pre>
+ *
+ * <pre>
+ *     <b><i>c</i></b> == (char)(((hibyte &amp; 0xff) &lt;&lt; 8)
+ *                         | (<b><i>b</i></b> &amp; 0xff))
+ * </pre>
+ *
+ * <pre> {@code
+ * interface ArchiveSearcher { String search(String target); }
+ * class App {
+ *   void showSearch(final String target)
+ *       throws InterruptedException {
+ *     Future<String> future
+ *       = executor.submit(new Callable<String>() {
+ *         public String call() {
+ *             return searcher.search(target);
+ *         }});
+ *     displayOtherThings(); // do other things while searching
+ *     try {
+ *       displayText(future.get()); // use future
+ *     } catch (ExecutionException ex) { cleanup(); return; }
+ *   }
+ * }}</pre>
+ */
+
+----------------------------------------------------
+
+[
+	"/**\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@code"],
+	["code-section", [
+		["code", [
+			["keyword", "this"],
+			["punctuation", "."],
+			"foo"
+		]]
+	]],
+	["punctuation", "}"],
+	" is never ",
+	["punctuation", "{"],
+	["keyword", "@code"],
+	["code-section", [
+		["code", [
+			["keyword", "null"]
+		]]
+	]],
+	["punctuation", "}"],
+	".\r\n *\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"code"
+		]],
+		["punctuation", ">"]
+	]],
+	["code-section", [
+		["line", [
+			["code", [
+				["class-name", "Foo"],
+				["punctuation", "."],
+				["function", "bar"],
+				["punctuation", "("],
+				["keyword", "null"],
+				["punctuation", ")"]
+			]]
+		]]
+	]],
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"code"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"tt"
+		]],
+		["punctuation", ">"]
+	]],
+	["code-section", [
+		["line", [
+			["code", [
+				["class-name", "Foo"]
+			]]
+		]]
+	]],
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"tt"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"code"
+		]],
+		["punctuation", ">"]
+	]],
+	["code-section", [
+		"* ",
+		["line", [
+			["code", [
+				["keyword", "for"],
+				["punctuation", "("],
+				["keyword", "int"],
+				" i ",
+				["operator", "="],
+				["number", "0"],
+				["punctuation", ";"],
+				" i ",
+				["operator", "<"],
+				" array",
+				["punctuation", "."],
+				"length",
+				["punctuation", ";"],
+				" i",
+				["operator", "++"],
+				["punctuation", ")"],
+				["punctuation", "{"]
+			]]
+		]],
+		"\r\n *     ",
+		["line", [
+			["code", [
+				"array",
+				["punctuation", "["],
+				"i",
+				["punctuation", "]"],
+				["operator", "+="],
+				["number", "1"],
+				["punctuation", ";"]
+			]]
+		]],
+		"\r\n * ",
+		["line", [
+			["code", [
+				["punctuation", "}"]
+			]]
+		]],
+		"\r\n * ",
+		["line", [
+			["code", [
+				["keyword", "return"],
+				" array",
+				["punctuation", ";"]
+			]]
+		]],
+		"\r\n *"
+	]],
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"code"
+		]],
+		["punctuation", ">"]
+	]],
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	["punctuation", "{"],
+	["keyword", "@code"],
+	["code-section", [
+		"*     ",
+		["code", [
+			["class-name", "String"],
+			" message ",
+			["operator", "="],
+			["class-name", "String"],
+			["punctuation", "."],
+			["function", "join"],
+			["punctuation", "("],
+			["string", "\"-\""],
+			["punctuation", ","],
+			["string", "\"Java\""],
+			["punctuation", ","],
+			["string", "\"is\""],
+			["punctuation", ","],
+			["string", "\"cool\""],
+			["punctuation", ")"],
+			["punctuation", ";"]
+		]],
+		"\r\n *     ",
+		["code", [
+			["comment", "// message returned is: \"Java-is-cool\""]
+		]],
+		"\r\n *"
+	]],
+	["punctuation", "}"],
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	["code-section", [
+		"*     ",
+		["line", [
+			["code", [
+				"dstBegin ",
+				["operator", "+"],
+				["punctuation", "("],
+				"srcEnd",
+				["operator", "-"],
+				"srcBegin",
+				["punctuation", ")"],
+				["operator", "-"],
+				["number", "1"]
+			]]
+		]],
+		"\r\n *"
+	]],
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	["code-section", [
+		"*     ",
+		["line", [
+			["tag", [
+				["tag", [
+					["punctuation", "<"],
+					"b"
+				]],
+				["punctuation", ">"]
+			]],
+			["tag", [
+				["tag", [
+					["punctuation", "<"],
+					"i"
+				]],
+				["punctuation", ">"]
+			]],
+			["code", [
+				"c"
+			]],
+			["tag", [
+				["tag", [
+					["punctuation", "</"],
+					"i"
+				]],
+				["punctuation", ">"]
+			]],
+			["tag", [
+				["tag", [
+					["punctuation", "</"],
+					"b"
+				]],
+				["punctuation", ">"]
+			]],
+			["code", [
+				["operator", "=="],
+				["punctuation", "("],
+				["keyword", "char"],
+				["punctuation", ")"],
+				["punctuation", "("],
+				["punctuation", "("],
+				["punctuation", "("],
+				"hibyte "
+			]],
+			["entity", "&amp;"],
+			["code", [
+				["number", "0xff"],
+				["punctuation", ")"]
+			]],
+			["entity", "&lt;"],
+			["entity", "&lt;"],
+			["code", [
+				["number", "8"],
+				["punctuation", ")"]
+			]]
+		]],
+		"\r\n *                         ",
+		["line", [
+			["code", [
+				["operator", "|"],
+				["punctuation", "("]
+			]],
+			["tag", [
+				["tag", [
+					["punctuation", "<"],
+					"b"
+				]],
+				["punctuation", ">"]
+			]],
+			["tag", [
+				["tag", [
+					["punctuation", "<"],
+					"i"
+				]],
+				["punctuation", ">"]
+			]],
+			["code", [
+				"b"
+			]],
+			["tag", [
+				["tag", [
+					["punctuation", "</"],
+					"i"
+				]],
+				["punctuation", ">"]
+			]],
+			["tag", [
+				["tag", [
+					["punctuation", "</"],
+					"b"
+				]],
+				["punctuation", ">"]
+			]],
+			["code", [
+			]],
+			["entity", "&amp;"],
+			["code", [
+				["number", "0xff"],
+				["punctuation", ")"],
+				["punctuation", ")"]
+			]]
+		]],
+		"\r\n *"
+	]],
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	["punctuation", "{"],
+	["keyword", "@code"],
+	["code-section", [
+		"* ",
+		["code", [
+			["keyword", "interface"],
+			["class-name", "ArchiveSearcher"],
+			["punctuation", "{"],
+			["class-name", "String"],
+			["function", "search"],
+			["punctuation", "("],
+			["class-name", "String"],
+			" target",
+			["punctuation", ")"],
+			["punctuation", ";"],
+			["punctuation", "}"]
+		]],
+		"\r\n * ",
+		["code", [
+			["keyword", "class"],
+			["class-name", "App"],
+			["punctuation", "{"]
+		]],
+		"\r\n *   ",
+		["code", [
+			["keyword", "void"],
+			["function", "showSearch"],
+			["punctuation", "("],
+			["keyword", "final"],
+			["class-name", "String"],
+			" target",
+			["punctuation", ")"]
+		]],
+		"\r\n *       ",
+		["code", [
+			["keyword", "throws"],
+			["class-name", "InterruptedException"],
+			["punctuation", "{"]
+		]],
+		"\r\n *     ",
+		["code", [
+			["class-name", "Future"],
+			["generics", [
+				["punctuation", "<"],
+				["class-name", "String"],
+				["punctuation", ">"]
+			]],
+			" future"
+		]],
+		"\r\n *       ",
+		["code", [
+			["operator", "="],
+			" executor",
+			["punctuation", "."],
+			["function", "submit"],
+			["punctuation", "("],
+			["keyword", "new"],
+			["class-name", "Callable"],
+			["generics", [
+				["punctuation", "<"],
+				["class-name", "String"],
+				["punctuation", ">"]
+			]],
+			["punctuation", "("],
+			["punctuation", ")"],
+			["punctuation", "{"]
+		]],
+		"\r\n *         ",
+		["code", [
+			["keyword", "public"],
+			["class-name", "String"],
+			["function", "call"],
+			["punctuation", "("],
+			["punctuation", ")"],
+			["punctuation", "{"]
+		]],
+		"\r\n *             ",
+		["code", [
+			["keyword", "return"],
+			" searcher",
+			["punctuation", "."],
+			["function", "search"],
+			["punctuation", "("],
+			"target",
+			["punctuation", ")"],
+			["punctuation", ";"]
+		]],
+		"\r\n *         ",
+		["code", [
+			["punctuation", "}"],
+			["punctuation", "}"],
+			["punctuation", ")"],
+			["punctuation", ";"]
+		]],
+		"\r\n *     ",
+		["code", [
+			["function", "displayOtherThings"],
+			["punctuation", "("],
+			["punctuation", ")"],
+			["punctuation", ";"],
+			["comment", "// do other things while searching"]
+		]],
+		"\r\n *     ",
+		["code", [
+			["keyword", "try"],
+			["punctuation", "{"]
+		]],
+		"\r\n *       ",
+		["code", [
+			["function", "displayText"],
+			["punctuation", "("],
+			"future",
+			["punctuation", "."],
+			["function", "get"],
+			["punctuation", "("],
+			["punctuation", ")"],
+			["punctuation", ")"],
+			["punctuation", ";"],
+			["comment", "// use future"]
+		]],
+		"\r\n *     ",
+		["code", [
+			["punctuation", "}"],
+			["keyword", "catch"],
+			["punctuation", "("],
+			["class-name", "ExecutionException"],
+			" ex",
+			["punctuation", ")"],
+			["punctuation", "{"],
+			["function", "cleanup"],
+			["punctuation", "("],
+			["punctuation", ")"],
+			["punctuation", ";"],
+			["keyword", "return"],
+			["punctuation", ";"],
+			["punctuation", "}"]
+		]],
+		"\r\n *   ",
+		["code", [
+			["punctuation", "}"]
+		]],
+		"\r\n * ",
+		["code", [
+			["punctuation", "}"]
+		]]
+	]],
+	["punctuation", "}"],
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"pre"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n */"
+]
+
+----------------------------------------------------
+
+Checks for code.
diff --git a/tests/languages/javadoc/entity_feature.test b/tests/languages/javadoc/entity_feature.test
new file mode 100644
index 0000000000..9789e9e793
--- /dev/null
+++ b/tests/languages/javadoc/entity_feature.test
@@ -0,0 +1,15 @@
+/**
+ * &lt;
+ */
+
+----------------------------------------------------
+
+[
+	"/**\r\n * ",
+	["entity", "&lt;"],
+	"\r\n */"
+]
+
+----------------------------------------------------
+
+Checks for HTML entities inside doc comments.
diff --git a/tests/languages/javadoc/keyword_feature.test b/tests/languages/javadoc/keyword_feature.test
index db56bb42b1..8f4baf65f3 100644
--- a/tests/languages/javadoc/keyword_feature.test
+++ b/tests/languages/javadoc/keyword_feature.test
@@ -1,69 +1,83 @@
-/**
- * @author
- * @deprecated
- * @exception
- * @param
- * @return
- * @see
- * @serial
- * @serialData
- * @serialField
- * @since
- * @throws
- * @version
- * {@code}
- * {@docRoot}
- * {@inheritDoc}
- * {@link}
- * {@linkplain}
- * {@literal}
- * {@value}
- */
-
-----------------------------------------------------
-
-[
-	"/**\n * ",
-	["keyword", "@author"],
-	"\n * ",
-	["keyword", "@deprecated"],
-	"\n * ",
-	["keyword", "@exception"],
-	"\n * ",
-	["keyword", "@param"],
-	"\n * ",
-	["keyword", "@return"],
-	"\n * ",
-	["keyword", "@see"],
-	"\n * ",
-	["keyword", "@serial"],
-	"\n * ",
-	["keyword", "@serialData"],
-	"\n * ",
-	["keyword", "@serialField"],
-	"\n * ",
-	["keyword", "@since"],
-	"\n * ",
-	["keyword", "@throws"],
-	"\n * ",
-	["keyword", "@version"],
-	"\n * ",
-	["punctuation", "{"], ["keyword", "@code"], ["punctuation", "}"],
-	"\n * ",
-	["punctuation", "{"], ["keyword", "@docRoot"], ["punctuation", "}"],
-	"\n * ",
-	["punctuation", "{"], ["keyword", "@inheritDoc"], ["punctuation", "}"],
-	"\n * ",
-	["punctuation", "{"], ["keyword", "@link"], ["punctuation", "}"],
-	"\n * ",
-	["punctuation", "{"], ["keyword", "@linkplain"], ["punctuation", "}"],
-	"\n * ",
-	["punctuation", "{"], ["keyword", "@literal"], ["punctuation", "}"],
-	"\n * ",
-	["punctuation", "{"], ["keyword", "@value"], ["punctuation", "}"],
-	"\n */"
-]
-
-----------------------------------------------------
-
-Checks for all keywords.
+/**
+ * @author
+ * @deprecated
+ * @exception
+ * @param
+ * @return
+ * @see
+ * @serial
+ * @serialData
+ * @serialField
+ * @since
+ * @throws
+ * @version
+ * {@code}
+ * {@docRoot}
+ * {@inheritDoc}
+ * {@link}
+ * {@linkplain}
+ * {@literal}
+ * {@value}
+ */
+
+----------------------------------------------------
+
+[
+	"/**\r\n * ",
+	["keyword", "@author"],
+	"\r\n * ",
+	["keyword", "@deprecated"],
+	"\r\n * ",
+	["keyword", "@exception"],
+	"\r\n * ",
+	["keyword", "@param"],
+	"\r\n * ",
+	["keyword", "@return"],
+	"\r\n * ",
+	["keyword", "@see"],
+	"\r\n * ",
+	["keyword", "@serial"],
+	"\r\n * ",
+	["keyword", "@serialData"],
+	"\r\n * ",
+	["keyword", "@serialField"],
+	"\r\n * ",
+	["keyword", "@since"],
+	"\r\n * ",
+	["keyword", "@throws"],
+	"\r\n * ",
+	["keyword", "@version"],
+	"\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@code"],
+	["punctuation", "}"],
+	"\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@docRoot"],
+	["punctuation", "}"],
+	"\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@inheritDoc"],
+	["punctuation", "}"],
+	"\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@link"],
+	["punctuation", "}"],
+	"\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@linkplain"],
+	["punctuation", "}"],
+	"\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@literal"],
+	["punctuation", "}"],
+	"\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@value"],
+	["punctuation", "}"],
+	"\r\n */"
+]
+
+----------------------------------------------------
+
+Checks for all keywords.
diff --git a/tests/languages/javadoc/parameter_feature.test b/tests/languages/javadoc/parameter_feature.test
index 98e12ed902..33f25b2b7b 100644
--- a/tests/languages/javadoc/parameter_feature.test
+++ b/tests/languages/javadoc/parameter_feature.test
@@ -1,20 +1,20 @@
-/**
- * @param foo an argument.
- * @param bar another argument.
- */
-
-----------------------------------------------------
-
-[
-	"/**\n * ",
-	["keyword", "@param"],
-	["parameter", "foo"],
-	" an argument.\n * ",
-	["keyword", "@param"],
-	["parameter", "bar"],
-	" another argument.\n */"
-]
-
-----------------------------------------------------
-
-Checks for parameters.
+/**
+ * @param foo an argument.
+ * @param bar another argument.
+ */
+
+----------------------------------------------------
+
+[
+	"/**\r\n * ",
+	["keyword", "@param"],
+	["parameter", "foo"],
+	" an argument.\r\n * ",
+	["keyword", "@param"],
+	["parameter", "bar"],
+	" another argument.\r\n */"
+]
+
+----------------------------------------------------
+
+Checks for parameters.
diff --git a/tests/languages/javadoc/reference_feature.test b/tests/languages/javadoc/reference_feature.test
new file mode 100644
index 0000000000..b7df94ef09
--- /dev/null
+++ b/tests/languages/javadoc/reference_feature.test
@@ -0,0 +1,348 @@
+/**
+ * @throws IllegalArgumentException if the argument is negative.
+ * @see org.my.company.InfoClass for more information.
+ * @param <T> the first generic argument.
+ * {@linkplain #foo(char[], java.lang.String) foo}
+ *
+ * multi-line {@link
+ * #foo(char[], java.lang.String)}
+ *
+ * @see #field
+ * @see #method(Type, Type)
+ * @see #method(Type argname, Type argname)
+ * @see #constructor(Type, Type)
+ * @see #constructor(Type argname, Type argname)
+ * @see Class#field
+ * @see Class#method(Type, Type)
+ * @see Class#method(Type argname, Type argname)
+ * @see Class#constructor(Type, Type)
+ * @see Class#constructor(Type argname, Type argname)
+ * @see Class.NestedClass
+ * @see Class
+ * @see foo.bar.Class#field
+ * @see foo.bar.Class#method(Type, Type)
+ * @see foo.bar.Class#method(Type argname, Type argname)
+ * @see foo.bar.Class#constructor(Type, Type)
+ * @see foo.bar.Class#constructor(Type argname, Type argname)
+ * @see foo.bar.Class.NestedClass
+ * @see foo.bar.Class
+ */
+
+----------------------------------------------------
+
+[
+	"/**\r\n * ",
+	["keyword", "@throws"],
+	["reference", [
+		["class-name", "IllegalArgumentException"]
+	]],
+	" if the argument is negative.\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["namespace", [
+			"org",
+			["punctuation", "."],
+			"my",
+			["punctuation", "."],
+			"company",
+			["punctuation", "."]
+		]],
+		["class-name", "InfoClass"]
+	]],
+	" for more information.\r\n * ",
+	["keyword", "@param"],
+	["class-name", [
+		["punctuation", "<"],
+		"T",
+		["punctuation", ">"]
+	]],
+	" the first generic argument.\r\n * ",
+	["punctuation", "{"],
+	["keyword", "@linkplain"],
+	["reference", [
+		["punctuation", "#"],
+		["function", "foo"],
+		["punctuation", "("],
+		["keyword", "char"],
+		["punctuation", "["],
+		["punctuation", "]"],
+		["punctuation", ","],
+		["namespace", [
+			"java",
+			["punctuation", "."],
+			"lang",
+			["punctuation", "."]
+		]],
+		["class-name", "String"],
+		["punctuation", ")"]
+	]],
+	" foo",
+	["punctuation", "}"],
+
+	"\r\n *\r\n * multi-line ",
+	["punctuation", "{"],
+	["keyword", "@link"],
+	"\r\n * ",
+	["reference", [
+		["punctuation", "#"],
+		["function", "foo"],
+		["punctuation", "("],
+		["keyword", "char"],
+		["punctuation", "["],
+		["punctuation", "]"],
+		["punctuation", ","],
+		["namespace", [
+			"java",
+			["punctuation", "."],
+			"lang",
+			["punctuation", "."]
+		]],
+		["class-name", "String"],
+		["punctuation", ")"]
+	]],
+	["punctuation", "}"],
+
+	"\r\n *\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["punctuation", "#"],
+		["field", "field"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["punctuation", "#"],
+		["function", "method"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		["punctuation", ","],
+		["class-name", "Type"],
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["punctuation", "#"],
+		["function", "method"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ","],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["punctuation", "#"],
+		["function", "constructor"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		["punctuation", ","],
+		["class-name", "Type"],
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["punctuation", "#"],
+		["function", "constructor"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ","],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["field", "field"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["function", "method"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		["punctuation", ","],
+		["class-name", "Type"],
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["function", "method"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ","],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["function", "constructor"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		["punctuation", ","],
+		["class-name", "Type"],
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["function", "constructor"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ","],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["class-name", "Class"],
+		["punctuation", "."],
+		["class-name", "NestedClass"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["class-name", "Class"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["namespace", [
+			"foo",
+			["punctuation", "."],
+			"bar",
+			["punctuation", "."]
+		]],
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["field", "field"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["namespace", [
+			"foo",
+			["punctuation", "."],
+			"bar",
+			["punctuation", "."]
+		]],
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["function", "method"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		["punctuation", ","],
+		["class-name", "Type"],
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["namespace", [
+			"foo",
+			["punctuation", "."],
+			"bar",
+			["punctuation", "."]
+		]],
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["function", "method"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ","],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["namespace", [
+			"foo",
+			["punctuation", "."],
+			"bar",
+			["punctuation", "."]
+		]],
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["function", "constructor"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		["punctuation", ","],
+		["class-name", "Type"],
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["namespace", [
+			"foo",
+			["punctuation", "."],
+			"bar",
+			["punctuation", "."]
+		]],
+		["class-name", "Class"],
+		["punctuation", "#"],
+		["function", "constructor"],
+		["punctuation", "("],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ","],
+		["class-name", "Type"],
+		" argname",
+		["punctuation", ")"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["namespace", [
+			"foo",
+			["punctuation", "."],
+			"bar",
+			["punctuation", "."]
+		]],
+		["class-name", "Class"],
+		["punctuation", "."],
+		["class-name", "NestedClass"]
+	]],
+	"\r\n * ",
+	["keyword", "@see"],
+	["reference", [
+		["namespace", [
+			"foo",
+			["punctuation", "."],
+			"bar",
+			["punctuation", "."]
+		]],
+		["class-name", "Class"]
+	]],
+	"\r\n */"
+]
+
+----------------------------------------------------
+
+Checks for references.
diff --git a/tests/languages/javadoc/tag_feature.test b/tests/languages/javadoc/tag_feature.test
index 81b49a51f5..a32187ffa8 100644
--- a/tests/languages/javadoc/tag_feature.test
+++ b/tests/languages/javadoc/tag_feature.test
@@ -1,117 +1,121 @@
-/**
- * <p>
- * <table>
- *     <tr>
- *         <td>
- *             foo
- *         </td>
- *         <td>
- *             bar
- *         </td>
- *     </tr>
- * </table>
- * <a href="example.com">some link</a>
- */
-
-----------------------------------------------------
-
-[
-	"/**\n * ",
-	["tag", [
-		["tag", [
-			["punctuation", "<"],
-			"p"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n * ",
-	["tag", [
-		["tag", [
-			["punctuation", "<"],
-			"table"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n *     ",
-	["tag", [
-		["tag", [
-			["punctuation", "<"],
-			"tr"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n *         ",
-	["tag", [
-		["tag", [
-			["punctuation", "<"],
-			"td"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n *             foo\n *         ",
-	["tag", [
-		["tag", [
-			["punctuation", "</"],
-			"td"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n *         ",
-	["tag", [
-		["tag", [
-			["punctuation", "<"],
-			"td"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n *             bar\n *         ",
-	["tag", [
-		["tag", [
-			["punctuation", "</"],
-			"td"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n *     ",
-	["tag", [
-		["tag", [
-			["punctuation", "</"],
-			"tr"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n * ",
-	["tag", [
-		["tag", [
-			["punctuation", "</"],
-			"table"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n * ",
-	["tag", [
-		["tag", [
-			["punctuation", "<"], "a"]],
-		["attr-name", ["href"]],
-		["attr-value", [
-			["punctuation", "="],
-			["punctuation", "\""],
-			"example.com",
-			["punctuation", "\""]
-		]],
-		["punctuation", ">"]
-	]],
-	"some link",
-	["tag", [
-		["tag", [
-			["punctuation", "</"],
-			"a"
-		]],
-		["punctuation", ">"]
-	]],
-	"\n */"
-]
-
-----------------------------------------------------
-
-Checks for HTML tags inside doc comments.
+/**
+ * <p>
+ * <table>
+ *     <tr>
+ *         <td>
+ *             foo
+ *         </td>
+ *         <td>
+ *             bar
+ *         </td>
+ *     </tr>
+ * </table>
+ * <a href="example.com">some link</a>
+ */
+
+----------------------------------------------------
+
+[
+	"/**\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"p"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"table"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *     ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"tr"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *         ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"td"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *             foo\r\n *         ",
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"td"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *         ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"td"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *             bar\r\n *         ",
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"td"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n *     ",
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"tr"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"table"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n * ",
+	["tag", [
+		["tag", [
+			["punctuation", "<"],
+			"a"
+		]],
+		["attr-name", [
+			"href"
+		]],
+		["attr-value", [
+			["punctuation", "="],
+			["punctuation", "\""],
+			"example.com",
+			["punctuation", "\""]
+		]],
+		["punctuation", ">"]
+	]],
+	"some link",
+	["tag", [
+		["tag", [
+			["punctuation", "</"],
+			"a"
+		]],
+		["punctuation", ">"]
+	]],
+	"\r\n */"
+]
+
+----------------------------------------------------
+
+Checks for HTML tags inside doc comments.