feat(language-core): infer prop JSDoc from defineModel's leading comments (#5211)

Author: KazariEX

Diff for: packages/component-meta/tests/index.spec.ts

@@ -32,47 +32,41 @@ const worker = (checker: ComponentMetaChecker, withTsconfig: boolean) => describ
 		const onUpdateFoo = meta.events.find(event => event.name === 'update:foo');
 
 		const bar = meta.props.find(prop => prop.name === 'bar');
-		const onUpdateBar = meta.events.find(event => event.name === 'update:bar');
-
-		const baz = meta.props.find(prop => prop.name === 'baz');
-		const bazModifiers = meta.props.find(prop => prop.name === 'bazModifiers');
-		const onUpdateBaz = meta.events.find(event => event.name === 'update:baz');
+		const barModifiers = meta.props.find(prop => prop.name === 'barModifiers');
+		const onUpdateBaz = meta.events.find(event => event.name === 'update:bar');
 
 		expect(modelValue).toBeDefined();
 		expect(modelValue?.default).toBeUndefined();
-		expect(modelValue?.required).toBeFalsy();
-		expect(modelValue?.type).toEqual('number | undefined');
-		expect(modelValue?.schema).toEqual({
-			kind: 'enum',
-			type: 'number | undefined',
-			schema: ['undefined', 'number'],
-		});
+		expect(modelValue?.required).toBeTruthy();
+		expect(modelValue?.type).toEqual('number');
+		expect(modelValue?.description).toEqual('required number modelValue');
+		expect(modelValue?.schema).toEqual('number');
 		expect(onUpdateModelValue).toBeDefined();
 
 		expect(foo).toBeDefined();
-		expect(foo?.default).toBeUndefined();
-		expect(foo?.required).toBeTruthy();
-		expect(foo?.type).toEqual('string[]');
+		expect(foo?.default).toBe('false');
+		expect(foo?.required).toBeFalsy();
+		expect(foo?.type).toEqual('boolean | undefined');
+		expect(foo?.description).toEqual('optional boolean foo with default false');
 		expect(foo?.schema).toEqual({
-			kind: 'array',
-			type: 'string[]',
-			schema: ['string'],
+			kind: 'enum',
+			type: 'boolean | undefined',
+			schema: ['undefined', 'false', 'true'],
 		});
 		expect(onUpdateFoo).toBeDefined();
 
 		expect(bar).toBeDefined();
-		expect(bar?.default).toBe('false');
+		expect(bar?.default).toBeUndefined();
 		expect(bar?.required).toBeFalsy();
-		expect(bar?.type).toEqual('boolean | undefined');
+		expect(bar?.type).toEqual('string | undefined');
+		expect(bar?.description).toEqual('optional string bar with lazy and trim modifiers');
 		expect(bar?.schema).toEqual({
 			kind: 'enum',
-			type: 'boolean | undefined',
-			schema: ['undefined', 'false', 'true'],
+			type: 'string | undefined',
+			schema: ['undefined', 'string'],
 		});
-		expect(onUpdateBar).toBeDefined();
-
-		expect(baz).toBeDefined();
-		expect(bazModifiers).toBeDefined();
+		// TODO: The types of modifiers are inconsistent in the two running results
+		expect(barModifiers).toBeDefined();
 		expect(onUpdateBaz).toBeDefined();
 	});
 

Diff for: packages/language-core/lib/codegen/script/scriptSetup.ts

@@ -103,6 +103,15 @@ function* generateSetupFunction(
 	ctx.scriptSetupGeneratedOffset = options.getGeneratedLength() - scriptSetupRanges.importSectionEndOffset;
 
 	let setupCodeModifies: [Code[], number, number][] = [];
+	for (const { comments } of scriptSetupRanges.defineProp) {
+		if (comments) {
+			setupCodeModifies.push([
+				[``],
+				comments.start,
+				comments.end,
+			]);
+		}
+	}
 	if (scriptSetupRanges.defineProps) {
 		const { name, statement, callExp, typeArg } = scriptSetupRanges.defineProps;
 		setupCodeModifies.push(...generateDefineWithType(
@@ -491,6 +500,10 @@ function* generateComponentProps(
 		for (const defineProp of scriptSetupRanges.defineProp) {
 			const [propName, localName] = getPropAndLocalName(scriptSetup, defineProp);
 
+			if (defineProp.comments) {
+				yield generateSfcBlockSection(scriptSetup, defineProp.comments.start, defineProp.comments.end, codeFeatures.all);
+				yield newLine;
+			}
 			if (defineProp.isModel && !defineProp.name) {
 				yield propName!;
 			}

Diff for: packages/language-core/lib/codegen/template/elementProps.ts

@@ -135,7 +135,7 @@ export function* generateElementProps(
 						: wrapWith(
 							prop.loc.start.offset,
 							prop.loc.start.offset + 'v-model'.length,
-							ctx.codeFeatures.verification,
+							ctx.codeFeatures.withoutHighlightAndCompletion,
 							propName
 						)
 				),

Diff for: packages/language-core/lib/parsers/scriptSetupRanges.ts

@@ -20,6 +20,7 @@ type DefineProp = {
 	defaultValue?: TextRange;
 	required?: boolean;
 	isModel?: boolean;
+	comments?: TextRange;
 	// used by component-meta
 	argNode?: ts.Expression;
 };
@@ -206,6 +207,7 @@ export function parseScriptSetupRanges(
 					defaultValue,
 					required,
 					isModel: true,
+					comments: getCommentsRange(ts, node, parents, ast),
 					argNode: options,
 				});
 			}
@@ -283,6 +285,7 @@ export function parseScriptSetupRanges(
 					runtimeType,
 					defaultValue,
 					required,
+					comments: getCommentsRange(ts, node, parents, ast),
 					argNode: options,
 				});
 			}
@@ -589,3 +592,24 @@ function getStatementRange(
 	}
 	return statementRange;
 }
+
+function getCommentsRange(
+	ts: typeof import('typescript'),
+	node: ts.Node,
+	parents: ts.Node[],
+	ast: ts.SourceFile
+) {
+	for (let i = parents.length - 1; i >= 0; i--) {
+		if (ts.isStatement(node)) {
+			break;
+		}
+		node = parents[i];
+	}
+	const comments = ts.getLeadingCommentRanges(ast.text, node.pos);
+	if (comments?.length) {
+		return {
+			start: comments[0].pos,
+			end: comments.at(-1)!.end,
+		};
+	}
+}

Diff for: packages/tsc/tests/__snapshots__/dts.spec.ts.snap

@@ -299,22 +299,28 @@ export default _default;
 
 exports[`vue-tsc-dts > Input: reference-type-model/component.vue, Output: reference-type-model/component.vue.d.ts 1`] = `
 "type __VLS_PublicProps = {
-    modelValue?: number;
-    'foo': string[];
-    'bar'?: boolean;
-    'baz'?: string;
-    'bazModifiers'?: Partial<Record<'lazy' | 'trim', true>>;
+    /**
+     * required number modelValue
+     */
+    modelValue: number;
+    /**
+     * optional boolean foo with default false
+     */
+    'foo'?: boolean;
+    /**
+     * optional string bar with lazy and trim modifiers
+     */
+    'bar'?: string;
+    'barModifiers'?: Partial<Record<'lazy' | 'trim', true>>;
 };
 declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (value: number) => any;
-    "update:foo": (value: string[]) => any;
-    "update:bar": (value: boolean) => any;
-    "update:baz": (value: string) => any;
+    "update:foo": (value: boolean) => any;
+    "update:bar": (value: string) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
     "onUpdate:modelValue"?: (value: number) => any;
-    "onUpdate:foo"?: (value: string[]) => any;
-    "onUpdate:bar"?: (value: boolean) => any;
-    "onUpdate:baz"?: (value: string) => any;
+    "onUpdate:foo"?: (value: boolean) => any;
+    "onUpdate:bar"?: (value: string) => any;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;
 "

Diff for: test-workspace/component-meta/reference-type-model/component.vue

@@ -1,10 +1,18 @@
 <script setup lang="ts">
-defineModel<number>();
-defineModel<string[]>('foo', {
+/**
+ * required number modelValue
+ */
+defineModel<number>({
 	required: true,
 });
-defineModel<boolean>('bar', {
+/**
+ * optional boolean foo with default false
+ */
+defineModel<boolean>('foo', {
 	default: false,
 });
-defineModel<string, 'lazy' | 'trim'>('baz');
+/**
+ * optional string bar with lazy and trim modifiers
+ */
+defineModel<string, 'lazy' | 'trim'>('bar');
 </script>