On 01.09.2011 22: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.
By the way, another solution is to use another prologue directive:
"use documentation";
or vice-versa, "no documentation"; since it would be better to turn-off
the feature, but by default to have it in the console, tests and debug.
P.S.: want to embed the source-code transformation script I gave into
Narcissus as an extension (e.g. an option for compilation)?
njs script.js --with-doc
Dmitry.
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
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
