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.
Rather than trying to extend the core language, I suggest that this type of
functionality is better viewed as simply another form of reflection that would
be best modeled as a kind of Mirror. It should manifest it self as a module
that provides access to such mirrors. For example, you might access it as
var docMirrorFn = DocMirror.for(fn);
var helpStr = docMirrorFn.help();
var helpStrLocalized = docMirrorFn.helpLocale();
var helpStrI18N = docMirrorFn.helpLocale(someLocale);
var competeDoc = docMirrorFn.full({format: 'HTML'});
var src = docMirrorFn.sourceCode;
// etc.
Yeah, why not. Also is a variant. Though, for the end-user I'd like to
see all this stuff encapsulated somewhere and to get the needed thing as
just .help(...). But, yes, it can be done by a host-environment as a
debugger which provides this .help(...) which inside does this long
manipulations.
If a REPL provider wants to offer a "help" command it would implement it by
accessing an appropriate documentation mirror.
Yes.
The definition of the DocMirror module would define how the appropriate meta
data is obtained and even alternatives and fall backs for obtaining it that
does not require direct embedding in the loaded JS code.
My recommendation would be rather than trying to extend to the core language at this
time, experiment with defining such a module. At some point we may be ready to consider
"standardizing" such modules but even before that there is nothing preventing
community adoption of such a convention.
Yes, it's not a problem to write a pre-processor of doc-comments
(actually we have many auto-doc generation tools for JavaDocs), i.e.:
to turn:
/**
* connect
* @param {String} host
* @param {Number} port
* Connects to my awesome host
*/
function connect(host, port) { ... }
into the:
function connect(host, port) { ... }
connect.__doc__ = "connect\n@param {String} host\n@param {Number}
port\nConnects to my awesome host"
or even into the:
function connect(host, port) {
// ! pre-processor header !!
if (typeof host != "string") console.warning("connect: host must be a
string");
if (typeof port != "number") console.warning("connect: port must be a
number");
// ! end of pre-processor header !!
// rest of user-defined implementation
}
it's just a variant of course (we need not to show this embedded checker
in the `toString` decompilation of a function and to handle prologue
before for directives), but the general idea is this.
It's not the problem to write such a pre-processor, but pre-processor
means to do something additional manually by hands before the execution
and not all users use some building-tools for that. OTOH, we can write
an extension for e.g. Narcissus to handle it on the engine's level and
try will it go or not (but something suggests me that it will ;)).
Dmitry.
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
