TypeScript was actually an inspiration - and jsig draws heavily on TypeScript's inspirations (especially ES6, Go, and to some extent [particularly generics], C#).
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>.
I guess this complaint should really be pointed at TypeScript, or even to C#, but also to Jsig...
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'm wary of things like this. They tend to require more cognitive effort than either of the alternatives: strict typing or a purist version of duck typing. That javascript makes either of those difficult or impossible (the former for obvious reasons and the latter because of flexible implicit conversion rules and an inflexible message receiver mechanism) is a failing of javascript that can't really be bandaided over with something optional.
I just think that this is, with even the best intentions, extremely prone to bitrot.
I'm actually not really sure that it's more readable than the JSDoc way : /
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).
My issue with JSdoc is that it's based around some notion of constructor-based inheritance, rather than structure. This is find if you're writing type annotations for a compiler to optimize a single codebase, but breaks down when trying to describe APIs meant to interoperate with modules written independently. Could you give examples of "deeply nested callbacks"? The example you linked to is perfectly expressible in jsig as show in this gist: https://gist.github.com/jden/5317051
@cromwellian jsig can just be put in regular JavaScript comments. It's not really designed to be machine parseable, although a documentation generator (or other tooling) could easily extend it to do so. jsig's scope is concerned with succinctly expressing type information to programmers, whether inline with a function definition or in a readme. In that sense, it doesn't take an opinion as to how or where it should be embedded. Think of a jsig notation as a free-standing expression.
If adding signatures to a codebase, why not use the closure syntax? Because then you also get a compiler which gives you nice warnings as well as better minification.
