Add support for JSDoc syntax where type comes after name. #165

CHANGELOG.md

@@ -14,7 +14,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/)
 
 ### Fixed
 
-- WCA now resolves more declarations and mixins patterns ([#172](https://github.com/runem/web-component-analyzer/issues/172))
+- Improved logic for resolving declarations and mixins ([#172](https://github.com/runem/web-component-analyzer/issues/172))
+- Added support for JSDoc syntax where type comes after name (eg. `@fires my-event {MouseEvent}`) ([#165](https://github.com/runem/web-component-analyzer/issues/165))
 
 ### Changes
 

src/analyze/util/js-doc-util.ts

@@ -269,7 +269,7 @@ function parseJsDocValue(value: string | undefined): unknown {
 }
 
 /**
- * Parses "@tag {type} name description"
+ * Parses "@tag {type} name description" or "@tag name {type} description"
  * @param str
  */
 function parseJsDocTagString(str: string): JsDocTagParsed {
@@ -289,87 +289,106 @@ function parseJsDocTagString(str: string): JsDocTagParsed {
 		return quotedStr.replace(/^['"](.+)["']$/, (_, match) => match);
 	};
 
-	// Match tag
-	// Example: "  @mytag"
-	const tagResult = str.match(/^(\s*@(\S+))/);
-	if (tagResult == null) {
-		return jsDocTag;
-	} else {
-		// Move string to the end of the match
-		// Example: "  @mytag|"
-		moveStr(tagResult[1]);
-		jsDocTag.tag = tagResult[2];
-	}
-
-	// Match type
-	// Example: "   {MyType}"
-	const typeResult = str.match(/^(\s*{([\s\S]*)})/);
-	if (typeResult != null) {
-		// Move string to the end of the match
-		// Example: "  {MyType}|"
-		moveStr(typeResult[1]);
-		jsDocTag.type = typeResult[2];
-	}
+	const matchTag = () => {
+		// Match tag
+		// Example: "  @mytag"
+		const tagResult = str.match(/^(\s*@(\S+))/);
+		if (tagResult == null) {
+			return jsDocTag;
+		} else {
+			// Move string to the end of the match
+			// Example: "  @mytag|"
+			moveStr(tagResult[1]);
+			jsDocTag.tag = tagResult[2];
+		}
+	};
 
-	// Match optional name
-	// Example: "  [myname=mydefault]"
-	const defaultNameResult = str.match(/^(\s*\[([\s\S]+)\])/);
-	if (defaultNameResult != null) {
-		// Move string to the end of the match
-		// Example: "  [myname=mydefault]|"
-		moveStr(defaultNameResult[1]);
-
-		// Using [...] means that this doc is optional
-		jsDocTag.optional = true;
-
-		// Split the inner content between [...] into parts
-		// Example:  "myname=mydefault" => "myname", "mydefault"
-		const parts = defaultNameResult[2].split("=");
-		if (parts.length === 2) {
-			// Both name and default were given
-			jsDocTag.name = unqouteStr(parts[0]);
-			jsDocTag.default = parseJsDocValue(parts[1]);
-		} else if (parts.length !== 0) {
-			// No default was given
-			jsDocTag.name = unqouteStr(parts[0]);
+	const matchType = () => {
+		// Match type
+		// Example: "   {MyType}"
+		const typeResult = str.match(/^(\s*{([\s\S]*)})/);
+		if (typeResult != null) {
+			// Move string to the end of the match
+			// Example: "  {MyType}|"
+			moveStr(typeResult[1]);
+			jsDocTag.type = typeResult[2];
 		}
-	} else {
-		// else, match required name
-		// Example: "   myname"
-
-		// A name is needed some jsdoc tags making it possible to include omit "-"
-		// Therefore we don't look for "-" or line end if the name is required - in that case we only need to eat the first word to find the name.
-		const regex = JSDOC_TAGS_WITH_REQUIRED_NAME.includes(jsDocTag.tag) ? /^(\s*(\S+))/ : /^(\s*(\S+))((\s*-[\s\S]+)|\s*)($|[\r\n])/;
-		const nameResult = str.match(regex);
-		if (nameResult != null) {
-			// Move string to end of match
-			// Example: "   myname|"
-			moveStr(nameResult[1]);
-			jsDocTag.name = unqouteStr(nameResult[2].trim());
+	};
+
+	const matchName = () => {
+		// Match optional name
+		// Example: "  [myname=mydefault]"
+		const defaultNameResult = str.match(/^(\s*\[([\s\S]+)\])/);
+		if (defaultNameResult != null) {
+			// Move string to the end of the match
+			// Example: "  [myname=mydefault]|"
+			moveStr(defaultNameResult[1]);
+
+			// Using [...] means that this doc is optional
+			jsDocTag.optional = true;
+
+			// Split the inner content between [...] into parts
+			// Example:  "myname=mydefault" => "myname", "mydefault"
+			const parts = defaultNameResult[2].split("=");
+			if (parts.length === 2) {
+				// Both name and default were given
+				jsDocTag.name = unqouteStr(parts[0]);
+				jsDocTag.default = parseJsDocValue(parts[1]);
+			} else if (parts.length !== 0) {
+				// No default was given
+				jsDocTag.name = unqouteStr(parts[0]);
+			}
+		} else {
+			// else, match required name
+			// Example: "   myname"
+
+			// A name is needed some jsdoc tags making it possible to include omit "-"
+			// Therefore we don't look for "-" or line end if the name is required - in that case we only need to eat the first word to find the name.
+			const regex = JSDOC_TAGS_WITH_REQUIRED_NAME.includes(jsDocTag.tag) ? /^(\s*(\S+))/ : /^(\s*(\S+))((\s*-[\s\S]+)|\s*)($|[\r\n])/;
+			const nameResult = str.match(regex);
+			if (nameResult != null) {
+				// Move string to end of match
+				// Example: "   myname|"
+				moveStr(nameResult[1]);
+				jsDocTag.name = unqouteStr(nameResult[2].trim());
+			}
 		}
-	}
+	};
 
-	// Match comment
-	if (str.length > 0) {
-		// The rest of the string is parsed as comment. Remove "-" if needed.
-		jsDocTag.description = str.replace(/^\s*-\s*/, "").trim() || undefined;
-	}
+	const matchComment = () => {
+		// Match comment
+		if (str.length > 0) {
+			// The rest of the string is parsed as comment. Remove "-" if needed.
+			jsDocTag.description = str.replace(/^\s*-\s*/, "").trim() || undefined;
+		}
 
-	// Expand the name based on namespace and classname
-	if (jsDocTag.name != null) {
-		/**
-		 * The name could look like this, so we need to parse and the remove the class name and namespace from the name
-		 *   InputSwitch#[CustomEvent]input-switch-check-changed
-		 *   InputSwitch#input-switch-check-changed
-		 */
-		const match = jsDocTag.name.match(/(.*)#(\[.*\])?(.*)/);
-		if (match != null) {
-			jsDocTag.className = match[1];
-			jsDocTag.namespace = match[2];
-			jsDocTag.name = match[3];
+		// Expand the name based on namespace and classname
+		if (jsDocTag.name != null) {
+			/**
+			 * The name could look like this, so we need to parse and the remove the class name and namespace from the name
+			 *   InputSwitch#[CustomEvent]input-switch-check-changed
+			 *   InputSwitch#input-switch-check-changed
+			 */
+			const match = jsDocTag.name.match(/(.*)#(\[.*\])?(.*)/);
+			if (match != null) {
+				jsDocTag.className = match[1];
+				jsDocTag.namespace = match[2];
+				jsDocTag.name = match[3];
+			}
 		}
+	};
+
+	matchTag();
+	matchType();
+	matchName();
+
+	// Type can come both before and after "name"
+	if (jsDocTag.type == null) {
+		matchType();
 	}
 
+	matchComment();
+
 	return jsDocTag;
 }
 

test/flavors/custom-element/extending-test.ts

@@ -1,5 +1,5 @@
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 import { getComponentProp } from "../../helpers/util";
 
 tsTest("Correctly extends interface with interface from different file", t => {

test/flavors/custom-element/method-test.ts

@@ -1,5 +1,5 @@
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 
 tsTest("Correctly finds method declarations on a class", t => {
 	const {

test/flavors/jsdoc/csspart-test.ts

@@ -1,5 +1,5 @@
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 
 tsTest("jsdoc: Discovers css parts with @csspart", t => {
 	const {
@@ -13,7 +13,7 @@ tsTest("jsdoc: Discovers css parts with @csspart", t => {
 	 }
 	 `);
 
-	const { cssParts } = result.componentDefinitions[0].declaration;
+	const { cssParts } = result.componentDefinitions[0].declaration!;
 
 	t.is(cssParts.length, 1);
 	t.is(cssParts[0].name, "thumb");

test/flavors/jsdoc/description-test.ts

@@ -21,7 +21,7 @@ tsTest("jsdoc: Correctly discovers the description in the jsdoc", t => {
 	 }
 	 `);
 
-	const declaration = result.componentDefinitions[0].declaration;
+	const declaration = result.componentDefinitions[0].declaration!;
 
 	t.is(
 		declaration.jsDoc?.description,

test/flavors/jsdoc/discover-global-test.ts

@@ -1,5 +1,5 @@
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 
 tsTest("jsdoc: Discovers global features on HTMLElement", t => {
 	const {

test/flavors/jsdoc/element-test.ts

@@ -1,5 +1,5 @@
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 
 tsTest("jsdoc: Discovers custom elements with @element", t => {
 	const {

test/flavors/jsdoc/event-test.ts

@@ -1,4 +1,4 @@
-import { isAssignableToSimpleTypeKind, SimpleType, SimpleTypeKind } from "ts-simple-type";
+import { isAssignableToSimpleTypeKind, SimpleType } from "ts-simple-type";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
 import { tsTest } from "../../helpers/ts-test";
 
@@ -14,28 +14,32 @@ tsTest("jsdoc: Discovers custom events with @fires", t => {
 	 }
 	 `);
 
-	const { events } = result.componentDefinitions[0].declaration;
+	const { events } = result.componentDefinitions[0].declaration!;
 
 	t.is(events.length, 1);
 	t.is(events[0].name, "my-event");
 	t.is(events[0].jsDoc?.description, "This is a comment");
 	t.truthy(isAssignableToSimpleTypeKind(events[0].type() as SimpleType, "ANY"));
 });
 
-tsTest("jsdoc: Discovers the detail type of custom events with @fires", t => {
+tsTest.only("jsdoc: Discovers the detail type of custom events with @fires", t => {
 	const {
 		results: [result]
 	} = analyzeTextWithCurrentTsModule(`
 	/**
 	 * @element
 	 * @fires {string} my-event
+	 * @fires my-second-event {number}
 	 */
 	 class MyElement extends HTMLElement { 
 	 }
 	 `);
 
-	const { events } = result.componentDefinitions[0].declaration;
-	t.truthy(isAssignableToSimpleTypeKind(events[0].type() as SimpleType, "STRING"));
+	const { events } = result.componentDefinitions[0].declaration!;
+	const myEvent = events.find(e => e.name === "my-event")!;
+	const mySecondEvent = events.find(e => e.name === "my-second-event")!;
+	t.truthy(isAssignableToSimpleTypeKind(myEvent.type() as SimpleType, "STRING"));
+	t.truthy(isAssignableToSimpleTypeKind(mySecondEvent.type() as SimpleType, "NUMBER"));
 });
 
 tsTest("jsdoc: Discovers events declared with @fires that includes extra jsdoc information", t => {
@@ -50,7 +54,7 @@ tsTest("jsdoc: Discovers events declared with @fires that includes extra jsdoc i
 	 }
 	 `);
 
-	const { events } = result.componentDefinitions[0].declaration;
+	const { events } = result.componentDefinitions[0].declaration!;
 
 	t.is(events.length, 1);
 	t.is(events[0].name, "input-switch-check-changed");

test/flavors/jsdoc/ignore-test.ts

@@ -1,5 +1,5 @@
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 
 tsTest("jsDoc: Handles @ignore jsdoc tag", t => {
 	const {
@@ -26,7 +26,7 @@ tsTest("jsDoc: Handles @ignore jsdoc tag", t => {
 		}
 	 `);
 
-	const { events, methods, members } = result.componentDefinitions[0]?.declaration;
+	const { events, methods, members } = result.componentDefinitions[0].declaration!;
 
 	t.is(events.length, 0);
 	t.is(members.length, 0);

test/flavors/jsdoc/jsdoc-types.ts

@@ -1,5 +1,5 @@
 import test from "ava";
-import { SimpleType, SimpleTypeKind } from "ts-simple-type";
+import { SimpleType } from "ts-simple-type";
 import { parseSimpleJsDocTypeExpression } from "../../../src/analyze/util/js-doc-util";
 
 test("Parse required and union", t => {

test/flavors/jsdoc/member-test.ts

@@ -1,4 +1,3 @@
-import { SimpleTypeKind } from "ts-simple-type";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
 import { tsTest } from "../../helpers/ts-test";
 import { assertHasMembers } from "../../helpers/util";

test/flavors/jsdoc/modifier-test.ts

@@ -1,6 +1,5 @@
-import { SimpleTypeKind } from "ts-simple-type";
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 import { assertHasMembers } from "../../helpers/util";
 
 tsTest("jsDoc: Handles @readonly on members", t => {

test/flavors/jsdoc/slot-test.ts

@@ -1,5 +1,5 @@
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 
 tsTest("jsdoc: Discovers slots with @slots", t => {
 	const {
@@ -13,7 +13,7 @@ tsTest("jsdoc: Discovers slots with @slots", t => {
 	 }
 	 `);
 
-	const { slots } = result.componentDefinitions[0].declaration;
+	const { slots } = result.componentDefinitions[0].declaration!;
 
 	t.is(slots.length, 1);
 	t.is(slots[0].name, "myslot");
@@ -32,7 +32,7 @@ tsTest("jsdoc: Discovers unnamed slots with @slots", t => {
 	 }
 	 `);
 
-	const { slots } = result.componentDefinitions[0].declaration;
+	const { slots } = result.componentDefinitions[0].declaration!;
 
 	t.is(slots.length, 1);
 	t.log(slots[0]);
@@ -55,7 +55,7 @@ tsTest("jsdoc: Discovers permitted tag names on @slot", t => {
 
 	const {
 		slots: [slot1, slot2]
-	} = result.componentDefinitions[0].declaration;
+	} = result.componentDefinitions[0].declaration!;
 
 	t.is(slot1.permittedTagNames!.length, 2);
 	t.deepEqual(slot1.permittedTagNames, ["div", "span"]);

test/flavors/jsdoc/visibility-test.ts

@@ -1,5 +1,5 @@
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 import { getComponentProp } from "../../helpers/util";
 
 tsTest("jsDoc: Handles visibility modifier on internal event", t => {
@@ -21,7 +21,7 @@ tsTest("jsDoc: Handles visibility modifier on internal event", t => {
 
 	const {
 		events: [event]
-	} = result.componentDefinitions[0]?.declaration;
+	} = result.componentDefinitions[0].declaration!;
 
 	t.truthy(event);
 	t.is(event.visibility, "private");

test/flavors/jsx/discover-global-test.ts

@@ -1,6 +1,5 @@
-import { SimpleTypeKind } from "ts-simple-type";
-import { tsTest } from "../../helpers/ts-test";
 import { analyzeTextWithCurrentTsModule } from "../../helpers/analyze-text-with-current-ts-module";
+import { tsTest } from "../../helpers/ts-test";
 import { assertHasMembers } from "../../helpers/util";
 
 tsTest("Discovers global features on JSX.IntrinsicAttributes", t => {