microsoft/TypeScript
1
0
Fork 0
mirror of https://github.com/microsoft/TypeScript.git synced 2026-05-16 07:13:45 -05:00
Code Issues Packages Projects Releases 212 Wiki Activity

Skip typedef in services getJSDocTags (#43677)

Browse Source 
* Symbols in services skip @typedef/@callback in jsdoc

Fixes #43534

* comment text skips jsdocs that are typedef-only

* Skip comment text from typedef-only jsdocs

* Skip whole comments instead of individual tags

* add semicolons

* retain comments from @callback + better comments
This commit is contained in:
Nathan Shively-Sanders
2021-06-23 16:19:14 -07:00
committed by GitHub
parent ece76e8a63
commit aee779ac7d
3 changed files with 263 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
src/services/jsDoc.ts
View File

@@ -92,9 +92,20 @@ namespace ts.JsDoc {
// from Array<T> - Array<string> and Array<number>
const parts: SymbolDisplayPart[][] = [];
forEachUnique(declarations, declaration => {
for (const { comment } of getCommentHavingNodes(declaration)) {
if (comment === undefined) continue;
const newparts = getDisplayPartsFromComment(comment, checker);
for (const jsdoc of getCommentHavingNodes(declaration)) {
// skip comments containing @typedefs since they're not associated with particular declarations
// Exceptions:
// - @typedefs are themselves declarations with associated comments
// - @param or @return indicate that the author thinks of it as a 'local' @typedef that's part of the function documentation
if (jsdoc.comment === undefined
|| isJSDoc(jsdoc)
&& declaration.kind !== SyntaxKind.JSDocTypedefTag && declaration.kind !== SyntaxKind.JSDocCallbackTag
&& jsdoc.tags
&& jsdoc.tags.some(t => t.kind === SyntaxKind.JSDocTypedefTag || t.kind === SyntaxKind.JSDocCallbackTag)
&& !jsdoc.tags.some(t => t.kind === SyntaxKind.JSDocParameterTag || t.kind === SyntaxKind.JSDocReturnTag)) {
continue;
}
const newparts = getDisplayPartsFromComment(jsdoc.comment, checker);
if (!contains(parts, newparts, isIdenticalListOfDisplayParts)) {
parts.push(newparts);
}
@@ -122,13 +133,21 @@ namespace ts.JsDoc {
export function getJsDocTagsFromDeclarations(declarations?: Declaration[], checker?: TypeChecker): JSDocTagInfo[] {
// Only collect doc comments from duplicate declarations once.
const tags: JSDocTagInfo[] = [];
const infos: JSDocTagInfo[] = [];
forEachUnique(declarations, declaration => {
for (const tag of getJSDocTags(declaration)) {
tags.push({ name: tag.tagName.text, text: getCommentDisplayParts(tag, checker) });
const tags = getJSDocTags(declaration);
// skip comments containing @typedefs since they're not associated with particular declarations
// Exceptions:
// - @param or @return indicate that the author thinks of it as a 'local' @typedef that's part of the function documentation
if (tags.some(t => t.kind === SyntaxKind.JSDocTypedefTag || t.kind === SyntaxKind.JSDocCallbackTag)
&& !tags.some(t => t.kind === SyntaxKind.JSDocParameterTag || t.kind === SyntaxKind.JSDocReturnTag)) {
return;
}
for (const tag of tags) {
infos.push({ name: tag.tagName.text, text: getCommentDisplayParts(tag, checker) });
}
});
return tags;
return infos;
}
function getDisplayPartsFromComment(comment: string | readonly JSDocComment[], checker: TypeChecker | undefined): SymbolDisplayPart[] {