__doc__ for functions, classes, objects etc.

Dmitry A. Soshnikov dmitry.soshnikov at gmail.com
Wed Aug 31 01:57:48 PDT 2011


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 at param {String} host\n at 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.


More information about the es-discuss mailing list