On 21.08.2011 22:26, Peter van der Zee wrote:
On Sun, Aug 7, 2011 at 6:56 PM, Dmitry A. Soshnikov
<[email protected]> wrote:
Hi,
What about to standardize (Python's) "__doc__"-umentation comments for JS?
What's the difference between that and the /** ... */ way of "JSDoc"?
/**
* This function does stuff
* @constructor
* @param {Object} foo
* @returns {Array}
*/
var f = function(){ ... };
It doesn't matter for me how *exactly* (syntactically) it will look
like. In this particular case the comment is outside a function's body
-- you then should consider and allow or not newlines after the
doc-comment, etc. Though, as well as in case of placing the comment
inside the body, but in this case I think we should mention that the
doc-comment is should be placed in the prologue.
What would a new language construct for this solve?
That's said, triple-strings by themselves (not only for doc-comments)
are very powerful construct to have and standardize. Did you work with
them in Python or CoffeeScript?
P.S.:
Another thing to notice. As was mentioned, it's good to have this
ability also for simple objects. From this viewpoint doc-string should
be set via property. But if I remember correctly, someone (all?) from
the committee didn't like Python's __names__ (despite the fact that JS
actually use them for __proto__, __noSuchMethod__, __count__,
__parent__, __iterator__ etc. -- non is standardized, stratified
meta-level won). But it would be great to have the ability to:
let foo = {
__doc__: "My awesome object",
x: 100, y: 200
};
Object.help(foo); // "My awesome object"
or simply `help(foo)`.
Dmitry.
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
