__doc__ for functions, classes, objects etc.

Dmitry A. Soshnikov dmitry.soshnikov at gmail.com
Tue Aug 23 03:55:54 PDT 2011


So, is that's all? Anyone else thinks it's a needed thing in the ES?

On 22.08.2011 14:57, Dmitry A. Soshnikov wrote:
> 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/20110823/c1f1e0e4/attachment.html>


More information about the es-discuss mailing list