I think that it's fine for very small projects, but if you want to share your docs, it's better to use an already conventioned syntax, which already solves edge cases (such as deeply nested callbacks).
For reference : http://usejsdoc.org/tags-callback.html
Does jsig have a provide for putting human readable comments in the signatures?
However TypeScript was optimized for building tooling. It also requires changing the actual executable code you write and investing in a workflow around the TypeScript compiler. With jsig, you just write a comment. My experience working almost exclusively in Node.js for the past year as shown me that plain JavaScript and minimal IDE support is sufficient if you embrace a philosophy of small, self-contained, loosely-coupled modules, each with their own tests and documentation. Writing this documentation in a clear way has been a pain point for me, however. jsig grew out of some of the conventions we've been using on my team to address the ad hoc or underspecified documentation we've dealt with.
With TypeScript, it's possible to write just in JavaScript and keep your TypeScript declarations in an external file (see, for example, [TSD](https://github.com/Diullei/tsd)) - but this is impractical. Plus, TypeScript does not support generic types, which are especially convenient for things like Callback<Buffer> or Promise<Buffer>.
An automated type checker is often the implementation of such a strict process that requires least effort.
It's really sad that different languages keep pushing `=>` for "function" type, instead of `->`, which has been the standard mathematical notations for a long time...
I think jsig's role is more to describe JavaScript, rather than to say the language is "doing it wrong"
I just think that this is, with even the best intentions, extremely prone to bitrot.
