using stampit with jsdoc

[foxaal]

This is an important issue, but I am new to all this -- please tell me if not the place to write this: I cannot find a recommended way to use jsdoc to document the creation of a stampit factory in addition to the pieces that go into it, i.e., method, state, and enclose pieces. I have had some success treating the factory as mixing in the three pieces like this: /\

• Use stampit to compose methods, state, and private data to create a factory object.
• @mixes platonicMethods
• @mixes platonicState
• @mixes platonicPrivate
• @return {Object} platonicFactory() */ platonicFactoryCreator = function ( ) { ....}

/\

• Methods going into the factory.
• @mixin / platonicMethods = { /*
  • Generated function used to test masking of the interface function of the same name.
  • @lend platonicMethods
  • @return {String} "platonic1() WIP" */ platonic1 : function ( ) {...} , BUT THIS SHOWS UP AS A STATIC FUNCTION in Jsdoc output.

Is there a better or accepted way?

[ericelliott]

Hi @foxaal,

This is currently an open question that I would love your feedback on.

Currently, you can get some benefits from annotating all your methods and enclose() functions, but when you're calling your stamp, automated tools don't have a good way to offer type hinting.

@koresar had some success with his Definitely Typed approach using TypeScript annotations. I'm not sure how well it works.

Please let me know how your experiments go. I would love to have good type hints and hopefully even some decent static analysis. =)

[foxaal]

Stampit "properly" organizes and simplifies how you code, and so should its generated documentation. This should just work. Jsdoc does not fit the bill because it must be coerced to fit the stampit pattern. This seems backward. I don't think it is the way forward, even though it can sort of work using @instance, @memberof, @enum, and other stuff. But then again, I don't even know the naming conventions, or if there are naming conventions, for the factory style, nor have I looked at the jsdoc source code.

Conjecture: there exists a sweet spot between human readability / usability ( high level language and pattern ) and what is really going on under the covers ( think Turing complete, BF language, etc. ). Javascript / stampit is an order of magnitude closer to that sweet spot than the classical inheritance strait jacket.

Question 1 : If the conjecture is true, all code using pure javascript needs to eventually get rewritten according the the stampit pattern ( unless an even better pattern is made usable ) . Assuming that all javascript applications need to be rewritten from scratch, then from a reasonably coarse grain perspective, what would the first block of stampit factories combine into ? A javascript interpreter ? Could these parts and pieces then be much more easily composed to produce an IDE and doc generator than trying to hack jsdoc, esprima, or what have you ?

Question 2 : Am I smoking too much javascript / stampit crack?

[ericelliott]

I would rewrite the conjecture:

Javascript / stampit is an order of magnitude closer to the sweet spot than the classical inheritance strait jacket.

Corollary: All code (in any language) using classical inheritance should be rewritten to use alternatives such as delegation, concatenation, composition, or the language's modules (node style modules, etc...).

Stampit makes that easy in JavaScript, and any other language that can make use of JavaScript modules (CoffeeScript, etc...).

Assuming that all javascript applications need to be rewritten from scratch

That's not usually the case, unless the apps have used very heavy classical inheritance throughout, in which case, they're probably due for a rewrite, anyway. ;)

what would the first block of stampit factories combine into?

I don't understand this question.

A javascript interpreter ? Could these parts and pieces then be much more easily composed to produce an IDE and doc generator than trying to hack jsdoc, esprima, or what have you ?

If you want something that compiles to JavaScript, can auto-generate documentation, and has support for Stampit, try Literate CoffeeScript -- but be aware, you're still missing out on quality static analysis.

Speaking of static analysis, I wonder if Flow could help. I haven't decided whether or not I would actually like to annotate types with Flow, but Facebook claims that it can use type inference to detect type errors even in JavaScript programs which are not annotated. I'd love to test that out.

[foxaal]

On the conjecture muse, here is another way to phrase my question: You have an editor and a browser that runs javascript. What is the first piece of code to write? Let's say it's stampit. A very high ratio in terms of utility to number of lines of code. An interesting question might be: what piece of code would have the next highest ratio? And would it use stampit? The Flow thing looks most interesting -- thanks for the pointer to that, and to Literate CoffeeScript. There's like a renaissance out there...

[backspaces]

Is there any reason not to just use Docco? I find the jsdoc approach less useful than a simple description of what the code is doing.

I guess it's important to distinguish between "dev" docs (how it all works) and "api" documentation (what the inputs and outputs are). For teams, the dev docs are more important, for users, api.

For stampit, I'd prefer dev, thus docco.

[foxaal]

Took a look at Docco -- shows me how crappy some of the comments littering my code really are... (I see underscore.js makes good use of it: http://underscorejs.org/docs/underscore.html ) But I want more. I am using stampit in a project, and the code seems so organized and easy to work with that so too should be its "self" documentation piece...maybe could be a namespace / refactoring tool as well...

[koresar]

This issue is rather old. I'll close it for now. Please, yield at me if you need this opened back.