__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?


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)`.


More information about the es-discuss mailing list