__doc__ for functions, classes, objects etc.

Allen Wirfs-Brock allen at wirfs-brock.com
Tue Aug 30 09:39:48 PDT 2011

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. 


More information about the es-discuss mailing list