factory.createSourceFile doesn't accept JSDoc node (typings issue)

[bali182]

Bug Report

🔎 Search Terms

• factory
• createSourceFile
• typings

🕗 Version & Regression Information

In v4.2.4 (current latest)

⏯ Playground Link

Playground link with relevant code

💻 Code

import { factory as f, SyntaxKind, NodeFlags } from 'typescript'

const comment = f.createJSDocComment('test', [])
const file = f.createSourceFile(
    [comment], // Error here as createSourceFile needs a Statement array.
    f.createToken(SyntaxKind.EndOfFileToken), 
    NodeFlags.None
)

🙁 Actual behavior

Compiler error in factory#createSourceFile when a JSDoc[] node supplied as Statement[] is expected. If it's casted to any, its fine at runtime, so I assume it's just an issue with typings.

🙂 Expected behavior

Accept JSDoc as a root level element for factory#createSourceFile

[RyanCavanaugh]

This might happen to work today, but it's not the API contract. You need to attach the JS Doc comment to an EmptyStatement or such.

[bali182]

Awesome didn't know that, thanks!

[bali182]

I started experimenting with this again, and it seems like there's no way to attach JSDocComments to other nodes. How do I do this? There seem to be no specific API method for this and setSyntheticLeadingComments doesn't accept JSDoc nodes. When parsing it seems to work beautifully, but how can I build this AST? There seems to be no jsDoc field on the nodes.

https://astexplorer.net/#/gist/63752d280452826f4031882c9943cd1a/dd91c7dbc66f70466e50f72a13c9a322fbd2d220

[RyanCavanaugh]

@rbuckton any advice?

[rbuckton]

The JSDoc is kind of a weird byproduct of how we support JSDoc for type information. In general, JSDoc nodes aren't built to be used with transforms, except in a few specific cases in some of our refactors. We don't emit JSDoc nodes attached to a statement or any other node. Instead we emit either the original comments from a source file, or synthetic leading and trailing comments attached to a node. If we were to emit both, we would somehow need to differentiate between parsed JSDoc comments and unparsed non-jsdoc comments on any node so that we don't emit them twice.

The only way you can have a transformer attach a "jsdoc" comment would be to use addSyntheticLeadingComment (or one of the other related "synthetic comment" functions), similar to what we do here:

TypeScript/src/services/refactors/convertOverloadListToSingleSignature.ts

Lines 156 to 165 in aa67b16

	setSyntheticLeadingComments(result, [{
	text: `*
	${newComment.split("\n").map(c => ` * ${c}`).join("\n")}
	`,
	kind: SyntaxKind.MultiLineCommentTrivia,
	pos: -1,
	end: -1,
	hasTrailingNewLine: true,
	hasLeadingNewline: true,
	}]);

One option is to use the createPrinter API to print out a formatted JSDoc comment, then strip off the leading /* and trailing */:

const printer = ts.createPrinter();
const output = printer.printNode(jsDoc).trim().replace(/^\/\*|\*\/$/, "");
addSyntheticLeadingComment(node, SyntaxKind.MultiLineCommentTrivia, output, /*hasTrailingNewLine*/ true);

This will have obvious caveats, since it would be difficult to make indentation match.

I could possibly see us modifying the synthetic comment functions to accept a JSDoc node, since we could differentiate on kind.

[bali182]

Great explanation, thank you! The printer API trick seems like a good solution, as I format the output anyways with prettier, so should be ok to have indentation issues.

[bali182]

But accepting JSDoc as leading/trailing comments would be amazing for codegen!