__doc__ for functions, classes, objects etc.

Dmitry A. Soshnikov dmitry.soshnikov at gmail.com
Sun Aug 7 12:30:30 PDT 2011


On 21.08.2011 22:26, Peter van der Zee wrote:
> On Sun, Aug 7, 2011 at 6:56 PM, Dmitry A. Soshnikov
> <dmitry.soshnikov at gmail.com>  wrote:
>> Hi,
>>
>> What about to standardize (Python's) "__doc__"-umentation comments for JS?
> What's the difference between that and the /** ... */ way of "JSDoc"?
>
> /**
>   * This function does stuff
>   * @constructor
>   * @param {Object} foo
>   * @returns {Array}
>   */
> var f = function(){ ... };
>

It doesn't matter for me how *exactly* (syntactically) it will look 
like. In this particular case the comment is outside a function's body 
-- you then should consider and allow or not newlines after the 
doc-comment, etc. Though, as well as in case of placing the comment 
inside the body, but in this case I think we should mention that the 
doc-comment is should be placed in the prologue.

> What would a new language construct for this solve?
>

That's said, triple-strings by themselves (not only for doc-comments) 
are very powerful construct to have and standardize. Did you work with 
them in Python or CoffeeScript?

P.S.:

Another thing to notice. As was mentioned, it's good to have this 
ability also for simple objects. From this viewpoint doc-string should 
be set via property. But if I remember correctly, someone (all?) from 
the committee didn't like Python's __names__ (despite the fact that JS 
actually use them for __proto__, __noSuchMethod__, __count__, 
__parent__, __iterator__ etc. -- non is standardized, stratified 
meta-level won). But it would be great to have the ability to:

let foo = {
   __doc__: "My awesome object",
   x: 100, y: 200
};

Object.help(foo); // "My awesome object"

or simply `help(foo)`.

Dmitry.


More information about the es-discuss mailing list