Hacker News Reader

Comment by leeoniya | Hacker News Reader

i recently learned you can actually have typescript annotations without [imo] polluting the syntax or requiring the TS compiler:

http://seg.phault.net/blog/2017/10/typescript-without-transp...

does anyone know if there are limitations to this style?

View on HN

Yes I wanted to do this initially but some things, like function overloads are kind of a mess. It depends really on what tags you need. You should look through the typescript issues related to jsdoc. Additionally, it's a bit of a mess trying to output declarations if you mix ts and js because enable checking js disallows emitting declarations, and declarations are only emitted for ts. You can get around this by setting your editor to check js, but leaving it off in the config. But then at that point I have no idea how you'd create documentation for that.

In general, contrary to what you'd expect, documentation options for ts seem poor. Typedocs is painful and ugly. I'll be trying DocFx next but it looks like it has a complicated workflow.

Also you should imo have some typescript experience to be able to write the jsdocs in a way that they work how you expect (e.g. typing a parameter as an object does not work how you would expect, it).

So next thing I thought was to just write js and accompany each file with a manual .d.ts definition. This works when you consume the exports of the file but it doesn't when you're within that file (see https://github.com/Microsoft/TypeScript/issues/30304) which makes it useless imo. Also even if it worked, now that I think about it, I'm again not sure how creating documentation for that would work.

In the end I've reluctantly settled for just switching completely to typescript and hopefully the documentation situation will improve when tsdoc gets farther along.

No limitations (only that it's a bit more verbose than just TS), this is canonical supported by the TypeScript powered tooling which VS Code provides by default on an JS project.

https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-i...

Cool, thanks. I generally love TS, but I have one project which I converted to TypeScript, and then reverted back to ES7, because the project is quite complex and the overhead of TS was not worth it. I wonder if by using this Jsdoc/ts strategy in critical sections I can get 80% of the benefit.

> the overhead of TS

Do you have any concrete examples? I would argue that a complex project that is already in TS benefits more from remaining in TS, so I’m curious what your reasoning was.

1) Import/export syntax hell. This project is 148 Javascript files, 12k LOC. Everything runs in both Node and Browser environments. Without TypeScript I just use CommonJS syntax and rewrite the scripts on the fly via a server-side pass through for a browser environment. But because of the module hell (import/export/script modules/relative vs absolute paths/defaults) I couldn't find a good formula for write once, run everywhere for this large project. I needed to be outputting 2 different builds to 2 different places which led to all kinds of path problems. This is very much unique to this project though, which has unique runtime require requirements.

2) Compile time overhead when iterating. For many visual development tasks it just takes too long to change something, compile and see results in the browser. Without TS it's 0 latency. With TS it was a few seconds. Without TS I could make 10 changes with 2 seconds latency, and perhaps I make 1 type mistake costing me 20 seconds of debug time, for a total of 40 seconds. With TS I make 10 changes with 5 seconds latency and zero mistakes but now total overhead if 50 seconds. I want to be able to get the documentation and static type checking benefits without giving up that instant feedback.

I suspect you can't do some of the fancier type contortions. For the simple case, I think it works just fine.

Reply on news.ycombinator.com