tsdoc VS proposal-type-annotations

For what it’s worth, there’s also TSDoc[1] which is TypeScript’s sorta-equivalent spiritual successor, and notably uses the same format as JSDoc. Inline type annotation is great—and I vastly prefer it to JSDoc as a type annotation mechanism—but supporting the breadth of documentation capability in an inline code position would probably be unwieldy no matter how you try to accommodate it.

1: https://tsdoc.org/

Docs? TSdoc + TypeDoc or DocFX. Of particular interest, this can be used to generate JSON schema's, useful for REST / GraphQL

Nope, they look the same, at a glance, but they're not the same. JSDoc and TSDoc are different standards, developed by different teams.

JSDoc is a terrible standard. I would rather go for TypeScript + TSDoc, then use TypDoc to generate the actual documentation based on TS typings. Alternatively, you can go for Vue Styleguidist. It's an excellent tool, but, opposite to TSDoc it's not a standard, it's just a tool.

I am trying to use the @microsoft/tsdoc package to generate documentation for a given file. I followed the demo that hey have provided https://github.com/microsoft/tsdoc/tree/main/api-demo and it works for the sample input they provided, shown below.

Maybe this is of interest? https://tsdoc.org/

Awesome, thank you! Would you be willing to support TSDoc ?

That proposal is not fully compatible with Typescript: https://github.com/tc39/proposal-type-annotations?tab=readme...

They held a meeting a few months ago so it's alive but probably still years away.

https://github.com/tc39/proposal-type-annotations/issues/184

I particularly like this thread in the TC39 types proposal. TypeScript IS a development trojan horse and locks you into the Microsoft Way of being a JS developer.

Edit: There is a proposal to extend JavaScript with type annotations, which would allow ("a reasonably large subset") of TypeScript to run directly in the browser. Yay!

https://github.com/tc39/proposal-type-annotations

More importantly, TypeScript typically commits to build things into itself when the proposal in JavaScript reaches Stage 3. The pattern matching proposal in JavaScript is Stage 1, but depends on many other proposals as well that may or may not need to be at Stage 3 as well for it to work. This particular proposal is interested on pattern matching on JavaScript Objects and other primitives, just like Python does with it’s native primitives. These are also dynamic types which helps in some areas, but makes it harder than others. Additionally, the JavaScript type annotations proposal needs to possibly account for this. So it’s going to be awhile. Like many years.

this is exactly what I want from the _Types as Comments_ proposal[0] as I think it's the only way that types can feasibly become part of the language. It's hard to imagine how all of the concepts TS introduces via special syntax can be covered otherwise.

[0] https://tc39.es/proposal-type-annotations

Crossing my fingers that the proposal for allowing (browser-ignored) type annotations in javascript progresses: https://tc39.es/proposal-type-annotations/

Between that, HTTP2/3 and ES modules many of the downsides for building apps with no compile step are almost completely mitigated.

JSDoc can get you pretty far, but it can be clumsy sometimes. There’s a [TC39 proposal](https://github.com/tc39/proposal-type-annotations) to allow types to live in JS code and be treated as comments (similar with Python types today)