assert members lack JSDoc in IDE

Problem to be solved

members of the Assert type don’t show their jsdoc on the member properties.

For example, FailTag has comprehensive documentation. But when hovering on the symbol it’s all elided:

Design

One option that works is to keep the docstrings in the d.ts files too. The downside is having to keep them in sync. To solve that we could build the .js from .ts. If we need .js without .ts, then we’ll have to move the Assert type out of .d.ts, but I’m not sure we can then express it in JSDoc since it will be nested.

[turadg]

@turadg Did you have ideas I could explore on my end?

Nope. There’s no silver bullet so any improvement will be a tradeoff of competing concerns. I expect we’ll improve incrementally in small steps. If a clear path forward for the codebase emerges, I’ll try to document here.

[mhofman]

I am still against any solution that requires runtime code generation, and I also would prefer avoiding any solution that requires .d.ts file generation outside of a publish flow.

I do not fully understand where JSdoc fails here, and why it can’t do something supported in .d.ts. Or is the problem that we have a duplication of definitions between JSDoc and .d.ts that are not in sync ?