__doc__ for functions, classes, objects etc.

[Irakli Gozalishvili]

I also prototyped this idea mainly for node. Also, I figured out a hack with
a label, that make it work for spidermonkey.


Regards
--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/
Address: 29 Rue Saint-Georges, 75009 Paris, France <http://goo.gl/maps/3CHu>

On Thursday, 2011-09-01 at 20:28 , Dmitry A. Soshnikov wrote:

On 31.08.2011 18:38, Allen Wirfs-Brock wrote:

On Aug 31, 2011, at 1:57 AM, Dmitry A. Soshnikov wrote:

On 30.08.2011 20:39, Allen Wirfs-Brock wrote:

On Aug 30, 2011, at 12:39 AM, Dmitry A. Soshnikov wrote:

OK, let's up the topic. Seems there are no technical issues in the proposed
thing -- we can simply either accept it or not. The question is whether it's
needed and sound proposal and the feature to have in ECMAScript.

There certainly are technical issues.

To start, by making this part of the core language you would be defining a
feature that can be used by any application code. For example, a program
might choose to encode essential runtime metadata as its "documentation".
Because of that possibility, the [[Documentation]] information must always
be available at runtime. Minimizers or obfuscators could not remote
documentation comments because of the possibility of breaking such programs.

Sure, though I don't think that application level code have to be dependent
in logic on documentation string. The doc-string is just the _addition for
debug_. No more, no less. It's when you use a new lib (my example with
Redis's `get` method which should accept callback), you just get this help
directly "from here" without going to some websites (which can even be down
for this time) and solve the problems much faster. And for minified scripts,
I think the option "Remove doc-comments" is the case.

When designing language features, a designer always has some specific use
cases in mind. But that doesn't restrict users of the language from
discovering other use cases. Once a feature is incorporated into a language,
implementation have to support all possible use cases, not just the original
intended use case. That's why it is important for language designer to think
broadly about all conceivable uses and feature interaction when extending a
language. Sure, no application is required to have logic dependencies upon
the content of a documentation string but once they exist any application
could have such dependencies. As a language designers you have to think
about the implications of such usages. It isn't good enough to just say that
wasn't the intended use of the feature.

Yes, of course it's true, we have to consider the most hardcore
use-cases of our programs. Well, then I have to think on it, but the
first thing which comes in mind -- already mentioned "Remove
doc-comments" option for minifiers, i.e. a user himself is responsible
for this action. Moreover, minification is again mostly for
browser-scripting, where this help(...) functionality isn't so required
as it is for the server programming in the console.

And for the later case I wrote a simple version of such a pre-processor:
https://gist.github.com/1186853

Simple example:

/**
* sum
* @param {Number} x
* @param {Number} y
* The function of summation.
*/
function sum(x, y) {
return x + y;
}

/**
* multSum
* @param {Number} x
* @param {Number} y
* @param {String} value
* The function of calculation.
*/
function calculate(x, y, value) {
// comment
print(value + ": " + sum(x, y));
}

// ---------- Test documentation ----------

// Result:

// Help on "sum" function:
//
// /**
// * sum
// * @param {Number} x
// * @param {Number} y
// * The function of summation.
// */
help(sum);

// Help on "calculate" function:
//
// /**
// * multSum
// * @param {Number} x
// * @param {Number} y
// * @param {String} value
// * The function of calculation.
// */
help(calculate);

// ---------- Test guards ----------

sum(1, 2); // 3, OK

calculate(1, 2, "value"); // value: 3

sum(1, "2"); // TypeError: "y" must be a number

calculate(1, 2, 4); // TypeError: "value" must be a string

Dmitry.

_______________________________________________
es-discuss mailing list
es-discuss at mozilla.org
https://mail.mozilla.org/listinfo/es-discuss



-- 
Regards
--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/
Address: 29 Rue Saint-Georges, 75009 Paris, France <http://goo.gl/maps/3CHu>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110902/88a400ce/attachment-0001.html>