4 ms·
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 annotatio
by 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 agoJsDoc 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.