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.
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.
If a REPL provider wants to offer a "help" command it would implement it by
accessing an appropriate documentation mirror.
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.
Allen
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
