So, is that's all? Anyone else thinks it's a needed thing in the ES?
On 22.08.2011 14:57, Dmitry A. Soshnikov wrote:
On 22.08.2011 12:47, Irakli Gozalishvili wrote:
I'm very much interested in getting something like this! In fact I
have been useing similar documentation style for some time already:
function doc(lambda) {
var doc = /\/\*([\s\S]*)?\*\//.exec(String(lambda))
return doc ? doc[1].trim() : ''
}
function sum(a, b) {
/* Calculates sum of given `a` and `b` arguments */
return a + b;
}
doc(sum) \\ > "Calculates sum of given `a` and `b` arguments"
Unfortunately this does not works on spidermonkey based js engines :(
Right. That's why I raised this issue, because the functionality is
very powerful. Backing to my concrete example with redis, I just
wanted to understand why the heck client.get('x'), after setting
client.set('x', 10) returns for me `true`, but not 10. If I had this
help(...) functionality I'd be able to get the description right from
the console, saying that `.get` function should accept callback which
already returns the value: client.get('x', function(err, data) {return
data;}) -> 10.
I of course could go to the documentation website (what actually I did
after my fail tries :)), but I think it goes without saying that it
would be the best if I could do this right from the console! Besides,
this [[Documentation]] property can be used in hints (with showing
parameters and their types) when typing function name.
From this viewpoint Python just wins and IMO we should have this
feature in the ES.
Also I found that best way to support this on spidermonkey is via E4X
hacks
function sum(a, b) {
<doc>Calculates sum of given `a` and `b` arguments</doc>
return a + b
}
Unfortunately I don't have any solution working across all engines
that would not require multiline string escaping:
function sum(a, b) {
var doc = "Calculates \
sum of given\
`a` and `b` argumnets"
return a + b
}
Yes, it's another pros to have [[Documentation]] standardized.
On Sunday, 2011-08-07 at 21:30 , Dmitry A. Soshnikov wrote:
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] <mailto:[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)`.
I don't think we need special property for that, as anyone can just
use `doc` or whatever they decide, bigger issue IMO is a property
docs. How do you document `foo.x` if x is not a function or object ?
It was just an example. Mostly this doc is needed for functions.
Though, we can think how we can do this for every property.
Dmitry.
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
