Skip to content

Commit de09d37

Browse files
QjuhQjuh
committed
chore: improve warnings
1 parent 85c76fa commit de09d37

File tree

2 files changed

+49
-37
lines changed

2 files changed

+49
-37
lines changed

‎packages/api-extractor/src/generators/ApiModelGenerator.ts

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -627,7 +627,7 @@ export class ApiModelGenerator {
627627
if (!docComment && parent) {
628628
this._collector.messageRouter.addAnalyzerIssue(
629629
ExtractorMessageId.DjsMissingJSDoc,
630-
`The symbol ${parentApiItem.displayName}#constrcutor() has no matching jsdoc equivalent in the JavaScript source files.`,
630+
`The constructor ${parentApiItem.displayName}() has no matching jsdoc equivalent in the JavaScript source files.`,
631631
astDeclaration,
632632
);
633633
}
@@ -726,7 +726,7 @@ export class ApiModelGenerator {
726726
if (!docComment && parent) {
727727
this._collector.messageRouter.addAnalyzerIssue(
728728
ExtractorMessageId.DjsMissingJSDoc,
729-
`The symbol ${name} has no matching jsdoc equivalent in the JavaScript source files.`,
729+
`The class ${name} has no matching jsdoc equivalent in the JavaScript source files.`,
730730
astDeclaration,
731731
);
732732
}
@@ -805,7 +805,7 @@ export class ApiModelGenerator {
805805
if (!docComment && parent) {
806806
this._collector.messageRouter.addAnalyzerIssue(
807807
ExtractorMessageId.DjsMissingJSDoc,
808-
`The symbol ${parentApiItem.displayName}#constructor() has no matching jsdoc equivalent in the JavaScript source files.`,
808+
`The constructor signature ${parentApiItem.displayName}() has no matching jsdoc equivalent in the JavaScript source files.`,
809809
astDeclaration,
810810
);
811811
}
@@ -961,7 +961,7 @@ export class ApiModelGenerator {
961961
if (!docComment && parent) {
962962
this._collector.messageRouter.addAnalyzerIssue(
963963
ExtractorMessageId.DjsMissingJSDoc,
964-
`The symbol ${name}() has no matching jsdoc equivalent in the JavaScript source files.`,
964+
`The function ${name}() has no matching jsdoc equivalent in the JavaScript source files.`,
965965
astDeclaration,
966966
);
967967
}
@@ -1092,7 +1092,7 @@ export class ApiModelGenerator {
10921092
if (!docComment && parent) {
10931093
this._collector.messageRouter.addAnalyzerIssue(
10941094
ExtractorMessageId.DjsMissingJSDoc,
1095-
`The symbol ${name} has no matching jsdoc equivalent in the JavaScript source files.`,
1095+
`The interface ${name} has no matching jsdoc equivalent in the JavaScript source files.`,
10961096
astDeclaration,
10971097
);
10981098
}
@@ -1182,7 +1182,7 @@ export class ApiModelGenerator {
11821182
if (!docComment && parent) {
11831183
this._collector.messageRouter.addAnalyzerIssue(
11841184
ExtractorMessageId.DjsMissingJSDoc,
1185-
`The symbol ${parentApiItem.displayName}#${name}() has no matching jsdoc equivalent in the JavaScript source files.`,
1185+
`The method ${parentApiItem.displayName}#${name}() has no matching jsdoc equivalent in the JavaScript source files.`,
11861186
astDeclaration,
11871187
);
11881188
}
@@ -1221,7 +1221,7 @@ export class ApiModelGenerator {
12211221

12221222
this._collector.messageRouter.addAnalyzerIssueForPosition(
12231223
ExtractorMessageId.DjsMissingTypeScriptType,
1224-
`The JSDoc comment for ${parentApiItem.displayName}#${name}() has no matching type equivalent in the TypeScript declaration file.`,
1224+
`The JSDoc comment for method ${parentApiItem.displayName}#${name}() has no matching type equivalent in the TypeScript declaration file.`,
12251225
this._mainSourceFile!,
12261226
0,
12271227
);
@@ -1294,7 +1294,7 @@ export class ApiModelGenerator {
12941294
if (!docComment && parent) {
12951295
this._collector.messageRouter.addAnalyzerIssue(
12961296
ExtractorMessageId.DjsMissingJSDoc,
1297-
`The symbol ${parentApiItem.displayName}#${name}() has no matching jsdoc equivalent in the JavaScript source files.`,
1297+
`The method signature ${parentApiItem.displayName}#${name}() has no matching jsdoc equivalent in the JavaScript source files.`,
12981298
astDeclaration,
12991299
);
13001300
}
@@ -1320,7 +1320,7 @@ export class ApiModelGenerator {
13201320
} else if (jsDoc) {
13211321
this._collector.messageRouter.addAnalyzerIssueForPosition(
13221322
ExtractorMessageId.DjsMissingTypeScriptType,
1323-
`The JSDoc comment for ${parentApiItem.displayName}#${name}() has no matching type equivalent in the TypeScript declaration file.`,
1323+
`The JSDoc comment for method signature ${parentApiItem.displayName}#${name}() has no matching type equivalent in the TypeScript declaration file.`,
13241324
this._mainSourceFile!,
13251325
0,
13261326
);
@@ -1366,7 +1366,8 @@ export class ApiModelGenerator {
13661366
private _processApiProperty(astDeclaration: AstDeclaration | null, context: IProcessAstEntityContext): void {
13671367
const { name, parentApiItem } = context;
13681368
const parent = context.parentDocgenJson as DocgenClassJson | DocgenInterfaceJson | DocgenTypedefJson | undefined;
1369-
const jsDoc = parent?.props?.find((prop) => prop.name === name);
1369+
const inherited = parent && 'extends' in parent ? this._isInherited(parent, name, parentApiItem.kind) : undefined;
1370+
const jsDoc = parent?.props?.find((prop) => prop.name === name) ?? inherited;
13701371
const isStatic: boolean = astDeclaration
13711372
? (astDeclaration.modifierFlags & ts.ModifierFlags.Static) !== 0
13721373
: parentApiItem.kind === ApiItemKind.Class || parentApiItem.kind === ApiItemKind.Interface
@@ -1376,11 +1377,7 @@ export class ApiModelGenerator {
13761377

13771378
let apiProperty: ApiProperty | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiProperty;
13781379

1379-
if (
1380-
apiProperty === undefined &&
1381-
(astDeclaration ||
1382-
!this._isInherited(parent as DocgenClassJson | DocgenInterfaceJson, jsDoc!, parentApiItem.kind))
1383-
) {
1380+
if (apiProperty === undefined && (astDeclaration || !inherited)) {
13841381
if (astDeclaration) {
13851382
const declaration: ts.Declaration = astDeclaration.declaration;
13861383
const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
@@ -1424,7 +1421,7 @@ export class ApiModelGenerator {
14241421
if (!docComment && parent) {
14251422
this._collector.messageRouter.addAnalyzerIssue(
14261423
ExtractorMessageId.DjsMissingJSDoc,
1427-
`The symbol ${parentApiItem.displayName}#${name} has no matching jsdoc equivalent in the JavaScript source files.`,
1424+
`The property ${parentApiItem.displayName}#${name} has no matching jsdoc equivalent in the JavaScript source files.`,
14281425
astDeclaration,
14291426
);
14301427
}
@@ -1455,7 +1452,7 @@ export class ApiModelGenerator {
14551452
} else if (parentApiItem.kind === ApiItemKind.Class || parentApiItem.kind === ApiItemKind.Interface) {
14561453
this._collector.messageRouter.addAnalyzerIssueForPosition(
14571454
ExtractorMessageId.DjsMissingTypeScriptType,
1458-
`The JSDoc comment for ${parentApiItem.displayName}#${name} has no matching type equivalent in the TypeScript declaration file.`,
1455+
`The JSDoc comment for property ${parentApiItem.displayName}#${name} has no matching type equivalent in the TypeScript declaration file.`,
14591456
this._mainSourceFile!,
14601457
0,
14611458
);
@@ -1484,11 +1481,13 @@ export class ApiModelGenerator {
14841481
containerKey,
14851482
) as ApiPropertySignature;
14861483
const parent = context.parentDocgenJson as DocgenInterfaceJson | DocgenPropertyJson | DocgenTypedefJson | undefined;
1487-
const jsDoc = parent?.props?.find((prop) => prop.name === name);
1484+
const inherited = parent && 'extends' in parent ? this._isInherited(parent, name, parentApiItem.kind) : undefined;
1485+
const jsDoc = parent?.props?.find((prop) => prop.name === name) ?? inherited;
14881486

14891487
if (
14901488
apiPropertySignature === undefined &&
1491-
(astDeclaration || !this._isInherited(parent as DocgenInterfaceJson, jsDoc!, parentApiItem.kind))
1489+
(astDeclaration || !inherited) &&
1490+
parentApiItem.kind !== ApiItemKind.Class
14921491
) {
14931492
if (astDeclaration) {
14941493
const propertySignature: ts.PropertySignature = astDeclaration.declaration as ts.PropertySignature;
@@ -1517,7 +1516,7 @@ export class ApiModelGenerator {
15171516
if (!docComment && parent) {
15181517
this._collector.messageRouter.addAnalyzerIssue(
15191518
ExtractorMessageId.DjsMissingJSDoc,
1520-
`The symbol ${parentApiItem.displayName}#${name} has no matching jsdoc equivalent in the JavaScript source files.`,
1519+
`The property signature ${parentApiItem.displayName}#${name} has no matching jsdoc equivalent in the JavaScript source files.`,
15211520
astDeclaration,
15221521
);
15231522
}
@@ -1539,10 +1538,10 @@ export class ApiModelGenerator {
15391538
fileLine: jsDoc && 'meta' in jsDoc ? jsDoc.meta.line : sourceLocation.sourceFileLine,
15401539
fileColumn: sourceLocation.sourceFileColumn,
15411540
});
1542-
} else if (parentApiItem.kind === ApiItemKind.Class || parentApiItem.kind === ApiItemKind.Interface) {
1541+
} else if (parentApiItem.kind === ApiItemKind.Interface) {
15431542
this._collector.messageRouter.addAnalyzerIssueForPosition(
15441543
ExtractorMessageId.DjsMissingTypeScriptType,
1545-
`The JSDoc comment for ${parentApiItem.displayName}#${name} has no matching type equivalent in the TypeScript declaration file.`,
1544+
`The JSDoc comment for property signature ${parentApiItem.displayName}#${name} has no matching type equivalent in the TypeScript declaration file.`,
15461545
this._mainSourceFile!,
15471546
0,
15481547
);
@@ -1610,7 +1609,7 @@ export class ApiModelGenerator {
16101609
if (!docComment && parent) {
16111610
this._collector.messageRouter.addAnalyzerIssue(
16121611
ExtractorMessageId.DjsMissingJSDoc,
1613-
`The symbol ${name} has no matching jsdoc equivalent in the JavaScript source files.`,
1612+
`The type alias ${name} has no matching jsdoc equivalent in the JavaScript source files.`,
16141613
astDeclaration,
16151614
);
16161615
}
@@ -1848,20 +1847,19 @@ export class ApiModelGenerator {
18481847

18491848
private _isInherited(
18501849
container: DocgenClassJson | DocgenInterfaceJson,
1851-
jsDoc: DocgenParamJson | DocgenPropertyJson,
1850+
propertyName: string,
18521851
containerKind: ApiItemKind,
1853-
): boolean {
1852+
): DocgenPropertyJson | undefined {
18541853
switch (containerKind) {
18551854
case ApiItemKind.Class: {
18561855
const token = (container as DocgenClassJson).extends;
18571856
const parentName = Array.isArray(token) ? token[0]?.[0]?.[0] : token?.types?.[0]?.[0]?.[0];
18581857
const parentJson = this._jsDocJson?.classes.find((clas) => clas.name === parentName);
18591858
if (parentJson) {
1860-
if (parentJson.props?.find((prop) => prop.name === jsDoc.name)) {
1861-
return true;
1862-
} else {
1863-
return this._isInherited(parentJson, jsDoc, containerKind);
1864-
}
1859+
return (
1860+
parentJson.props?.find((prop) => prop.name === propertyName) ??
1861+
this._isInherited(parentJson, propertyName, containerKind)
1862+
);
18651863
}
18661864

18671865
break;
@@ -1873,13 +1871,15 @@ export class ApiModelGenerator {
18731871
const parentJsons = parentNames?.map((name) =>
18741872
this._jsDocJson?.interfaces.find((inter) => inter.name === name),
18751873
);
1874+
if (propertyName === 'content') console.log(container.name, parentNames, parentJsons);
18761875
if (parentJsons?.length) {
18771876
for (const parentJson of parentJsons) {
1878-
if (
1879-
parentJson?.props?.find((prop) => prop.name === jsDoc.name) ||
1880-
this._isInherited(parentJson as DocgenInterfaceJson, jsDoc, containerKind)
1881-
) {
1882-
return true;
1877+
const result =
1878+
parentJson?.props?.find((prop) => prop.name === propertyName) ??
1879+
this._isInherited(parentJson as DocgenInterfaceJson, propertyName, containerKind);
1880+
1881+
if (result) {
1882+
return result;
18831883
}
18841884
}
18851885
}
@@ -1888,10 +1888,10 @@ export class ApiModelGenerator {
18881888
}
18891889

18901890
default:
1891-
console.log(`Unexpected parent of type ${containerKind} (${container.name}) of ${jsDoc?.name} `);
1891+
console.log(`Unexpected parent of type ${containerKind} (${container.name}) of ${propertyName} `);
18921892
}
18931893

1894-
return false;
1894+
return undefined;
18951895
}
18961896

18971897
private _isReadonly(astDeclaration: AstDeclaration): boolean {

‎packages/discord.js/tsdoc.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
3+
"extends": ["@discordjs/api-extractor/extends/tsdoc-base.json"],
4+
5+
"tagDefinitions": [
6+
{
7+
"tagName": "@unstable",
8+
"syntaxKind": "modifier"
9+
}
10+
],
11+
"supportForTags": { "@unstable": true }
12+
}

0 commit comments

Comments
 (0)