microsoft / microsoft/TypeScript
No supported way to get js doc tags from extraneous comments
Open
@sandersn is already working on this.
Since Feb 23, 2021.
Experience Enhancement
Help Wanted
Needs Investigation
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.3k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 132
Description
🔎 Search Terms
ts.getJSDocTags
JSDoc tag not found
🕗 Version & Regression Information
Seen in TS 4.0 and 4.1
- This is the behavior in every version I tried, and I reviewed the FAQ for entries about the compiler API
💻 Code
Consider the input file:
/** @foo */
/** @bar */
var x;
As far as I can tell, there's no supported compiler API to access the @foo jsdoc tag. I've resorted to casting ts.Node to {jsDoc?: ts.JSDoc[]}.
🙁 Actual behavior
ts.getJSDocTags and friends only give the @bar JSDoc tag
🙂 Expected behavior
That method, or another, to return both the @foo and @bar tags.
Full compiler code sample to repro
import * as ts from 'typescript';
const filename = 'some_code.ts';
const program = ts.createProgram(['some_code.ts'], {noEmit: true});
program.emit();
const sourceFile = program.getSourceFile(filename);
if (!sourceFile) {
throw new Error('could not get source file');
}
console.log(`getJSDocTags:`);
console.log([...getAllTags(sourceFile, (node) => ts.getJSDocTags(node))].map(
(t) => t.tagName.text));
console.log(`Accessing jsDoc directly:`);
console.log(
[...getAllTags(sourceFile, accessJsDoc)].map((t) => t.tagName.text));
function accessJsDoc(node: ts.Node): ts.JSDocTag[] {
const tags = [];
for (const jsDoc of (node as {jsDoc?: ts.JSDoc[]}).jsDoc ?? []) {
for (const tag of jsDoc.tags ?? []) {
tags.push(tag);
}
}
return tags;
}
type TagGetter = (node: ts.Node) => Iterable<ts.JSDocTag>;
function getAllTags(
node: ts.Node, getter: TagGetter, tags = new Set<ts.JSDocTag>()) {
for (const tag of getter(node)) {
tags.add(tag);
}
ts.forEachChild(node, (child) => {
getAllTags(child, getter, tags);
});
return tags;
}
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.