5 ms·

Jsig - precise & concise javascript signature notation

25 points by jasondenizac 14y ago

jasondenizac 14y ago
If you have feedback, please open an issue thread or pull request on github
arcatek 14y ago
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). For reference : http://usejsdoc.org/tags-callback.html http://usejsdoc.org/tags-callback.html
- jasondenizac 14y ago
  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 https://gist.github.com/jden/5317051
  - cromwellian 14y ago
    JsDoc does double duty though, because it simultaneously types the code and allows auto-generation of nicely formatted documentation. Does jsig have a provide for putting human readable comments in the signatures?
  - jasondenizac 14y ago
    @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.
opminion 14y ago
TypeScript comes to mind. It's for a different purpose (jsig is meant only for humans) but formal annotations, if successful, will be read by machine.
- jauco 14y ago
  moreover, I don't think that type annotations will provide much benefit if there's no strict process for validating them. An automated type checker is often the implementation of such a strict process that requires least effort.
- jasondenizac 14y ago
  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) 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>.
stormbrew 14y ago
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.
woah 14y ago
This is awesome. Thanks for doing this.
tomp 14y ago
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...
- jasondenizac 14y ago
  In this case, I am deferring to the notation adopted in the upcoming version of JavaScript, ES6 - see http://wiki.ecmascript.org/doku.php?id=harmony:arrow_function_syntax http://wiki.ecmascript.org/doku.php?id=harmony:arrow_functio... I think jsig's role is more to describe JavaScript, rather than to say the language is "doing it wrong"
- deleted 14y ago
  [deleted]
xxgreg 14y ago
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.

25 points by jasondenizac 14y ago

If you have feedback, please open an issue thread or pull request on github

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). For reference : http://usejsdoc.org/tags-callback.html http://usejsdoc.org/tags-callback.html

jasondenizac 14y ago
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 https://gist.github.com/jden/5317051
- cromwellian 14y ago
  JsDoc does double duty though, because it simultaneously types the code and allows auto-generation of nicely formatted documentation. Does jsig have a provide for putting human readable comments in the signatures?
- jasondenizac 14y ago
  @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.

opminion 14y ago

TypeScript comes to mind. It's for a different purpose (jsig is meant only for humans) but formal annotations, if successful, will be read by machine.

jauco 14y ago
moreover, I don't think that type annotations will provide much benefit if there's no strict process for validating them. An automated type checker is often the implementation of such a strict process that requires least effort.
jasondenizac 14y ago
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) 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>.

stormbrew 14y ago

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.

woah 14y ago

This is awesome. Thanks for doing this.

tomp 14y ago

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...

jasondenizac 14y ago
In this case, I am deferring to the notation adopted in the upcoming version of JavaScript, ES6 - see http://wiki.ecmascript.org/doku.php?id=harmony:arrow_function_syntax http://wiki.ecmascript.org/doku.php?id=harmony:arrow_functio... I think jsig's role is more to describe JavaScript, rather than to say the language is "doing it wrong"
deleted 14y ago
[deleted]

xxgreg 14y ago

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.