jsDoc and TypeScript have interrelated goals. While jsDoc is mainly about providing context in the form of comments to functions / classes / etc, it also tries to act as a type system. The problem with jsDoc's pseudo typesystem being that you have to now actively maintain a codebase AND the corresponding type annotations. In a massive codebase this is a tough thing to do and requires a lot of discipline. Not to mention that the type annotations written in jsDoc have no guarantees that they're ever correct. For instance, you could have a jsDoc annotation that states that a function always returns a number. But perhaps in some edge cases your function coerces the number to a string. You don't have a compiler to help you in this case, so you have to write unit tests to assert that your function works in various scenarios (essentially taking the responsibility of a compiler). Or even worse (but happens often) the function behavior changes completely and the jsDoc type annotations are completely irrelevant (and probably counterproductive to the reader).
Alternatively, typescript's type annotations are always up to date. If you change your code and it conflicts with a type annotation in typescript, the compiler will let you know that you have a mismatch: "Hey your function no longer returns numbers 100% of the time". Well written types (especially with a healthy dose of type alias, eg. type DateString = string) are self-documenting. Maybe you can add a sentence or two to the functions on top of your types as well.
I'm a front end developer working with JavaScript since 1996. I enjoy writing small, efficient libraries to other developers accomplish complicated tasks with less code.
Actually, when you're using VSCode, you can turn on TypeScript type checking for JavaScript with "implicitProjectConfig.checkJs": true". This tells the TypeScript language service to check the types for the JavaScript. When you add JSDoc comments, TypeScript uses those to understand the document's types. This means you get real time type checking in VSCode for plain ole JavaScript. This also includes features like symbol renaming across files, auto completion, go to definition, peek definition, go to type definition, find all references, etc. You can setup VSCode in settings for no explicit any for stricter type checking. If you try to change a type, VSCode will flag this error across all the files in your project where that type is used.
JSDoc lets you define custom types. You can import types from external files for reuse across your project. You can even do type casting. All of this while writing JavaScript. JSDocs with VSCode gives you type safety and intellisense for plain JavaScript. This means you're not limited to the JavaScript feature set that TypeScript supports. You can use whatever features currently supported by Babel, etc. If you've got a problematic line where type casting isn't working or you're using an expando property and don't want to escape it with [""], you can tell TypeScript to ignore it with:
// @ts-ignore
JSDoc comments are more verbose than the type declarations in TypeScript, but I personally prefer them because I know right where to look for a block of code's type information. The second benefit of JSDoc is that the comments can also be used to create HTML documentation for the code. In fact, the TypeScript team uses JSDoc comments in the TypeScript source code. JSDoc is the recommended way of providing documentation for TypeScript.
My point was mainly that jsDoc can step on TS shoes while adding context and description to your code.
On my personal projects, I never feel the need to use TS. While at work, however, I wish everyday that we had TS (and not just a bunch of outdated, badly formated jsDoc, like you describe)
jsDoc and TypeScript have interrelated goals. While jsDoc is mainly about providing context in the form of comments to functions / classes / etc, it also tries to act as a type system. The problem with jsDoc's pseudo typesystem being that you have to now actively maintain a codebase AND the corresponding type annotations. In a massive codebase this is a tough thing to do and requires a lot of discipline. Not to mention that the type annotations written in jsDoc have no guarantees that they're ever correct. For instance, you could have a jsDoc annotation that states that a function always returns a number. But perhaps in some edge cases your function coerces the number to a string. You don't have a compiler to help you in this case, so you have to write unit tests to assert that your function works in various scenarios (essentially taking the responsibility of a compiler). Or even worse (but happens often) the function behavior changes completely and the jsDoc type annotations are completely irrelevant (and probably counterproductive to the reader).
Alternatively, typescript's type annotations are always up to date. If you change your code and it conflicts with a type annotation in typescript, the compiler will let you know that you have a mismatch: "Hey your function no longer returns numbers 100% of the time". Well written types (especially with a healthy dose of type alias, eg.
type DateString = string) are self-documenting. Maybe you can add a sentence or two to the functions on top of your types as well.Actually, when you're using VSCode, you can turn on TypeScript type checking for JavaScript with "implicitProjectConfig.checkJs": true". This tells the TypeScript language service to check the types for the JavaScript. When you add JSDoc comments, TypeScript uses those to understand the document's types. This means you get real time type checking in VSCode for plain ole JavaScript. This also includes features like symbol renaming across files, auto completion, go to definition, peek definition, go to type definition, find all references, etc. You can setup VSCode in settings for no explicit any for stricter type checking. If you try to change a type, VSCode will flag this error across all the files in your project where that type is used.
JSDoc lets you define custom types. You can import types from external files for reuse across your project. You can even do type casting. All of this while writing JavaScript. JSDocs with VSCode gives you type safety and intellisense for plain JavaScript. This means you're not limited to the JavaScript feature set that TypeScript supports. You can use whatever features currently supported by Babel, etc. If you've got a problematic line where type casting isn't working or you're using an expando property and don't want to escape it with [""], you can tell TypeScript to ignore it with:
// @ts-ignoreJSDoc comments are more verbose than the type declarations in TypeScript, but I personally prefer them because I know right where to look for a block of code's type information. The second benefit of JSDoc is that the comments can also be used to create HTML documentation for the code. In fact, the TypeScript team uses JSDoc comments in the TypeScript source code. JSDoc is the recommended way of providing documentation for TypeScript.
may not be 100% true anymore: github.com/Microsoft/tsdoc
Nice comment, laying a more TypeScript approach.
My point was mainly that jsDoc can step on TS shoes while adding context and description to your code.
On my personal projects, I never feel the need to use TS. While at work, however, I wish everyday that we had TS (and not just a bunch of outdated, badly formated jsDoc, like you describe)
I do agree that it can be overkill to use TS as well, and that JSDoc is great tool in many or most circumstances :)