

Jsig - precise & concise javascript signature notation - jasondenizac
https://github.com/jden/jsig

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

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

------
tomp
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
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_functio...](http://wiki.ecmascript.org/doku.php?id=harmony:arrow_function_syntax)

I think jsig's role is more to describe JavaScript, rather than to say the
language is "doing it wrong"

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

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

~~~
jasondenizac
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>

~~~
jasondenizac
@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.

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

------
woah
This is awesome. Thanks for doing this.

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

