__doc__ for functions, classes, objects etc.

Dmitry A. Soshnikov dmitry.soshnikov at gmail.com
Mon Aug 22 03:57:30 PDT 2011


On 22.08.2011 12:47, Irakli Gozalishvili wrote:
> I'm very much interested in getting something like this! In fact I 
> have been useing similar documentation style for some time already:
>
> function doc(lambda) {
>   var doc = /\/\*([\s\S]*)?\*\//.exec(String(lambda))
>   return doc ? doc[1].trim() : ''
> }
>
> function sum(a, b) {
>   /* Calculates sum of given `a` and `b` arguments */
>   return a + b;
> }
>
> doc(sum) \\ > "Calculates sum of given `a` and `b` arguments"
>
> Unfortunately this does not works on spidermonkey based js engines :(
>

Right. That's why I raised this issue, because the functionality is very 
powerful. Backing to my concrete example with redis, I just wanted to 
understand why the heck client.get('x'), after setting client.set('x', 
10) returns for me `true`, but not 10. If I had this help(...) 
functionality I'd be able to get the description right from the console, 
saying that `.get` function should accept callback which already returns 
the value: client.get('x', function(err, data) {return data;}) -> 10.

I of course could go to the documentation website (what actually I did 
after my fail tries :)), but I think it goes without saying that it 
would be the best if I could do this right from the console! Besides, 
this [[Documentation]] property can be used in hints (with showing 
parameters and their types) when typing function name.

 From this viewpoint Python just wins and IMO we should have this 
feature in the ES.

> Also I found that best way to support this on spidermonkey is via E4X 
> hacks
>
> function sum(a, b) {
> <doc>Calculates sum of given `a` and `b` arguments</doc>
>   return a + b
> }
>
> Unfortunately I don't have any solution working across all engines 
> that would not require multiline string escaping:
>
> function sum(a, b) {
>   var doc = "Calculates \
>   sum of given\
>   `a` and `b` argumnets"
>
>   return a + b
> }
>
>

Yes, it's another pros to have [[Documentation]] standardized.

> On Sunday, 2011-08-07 at 21:30 , Dmitry A. Soshnikov wrote:
>
>> 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 <mailto: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)`.
>
> I don't think we need special property for that, as anyone can just 
> use `doc` or whatever they decide, bigger issue IMO is a property 
> docs. How do you document `foo.x` if x is not a function or object ?

It was just an example. Mostly this doc is needed for functions. Though, 
we can think how we can do this for every property.

Dmitry.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110822/6b701458/attachment.html>


More information about the es-discuss mailing list