__doc__ for functions, classes, objects etc.

Dmitry Soshnikov dmitry.soshnikov at gmail.com
Fri Sep 2 09:04:42 PDT 2011


On 01.09.2011 22:28, Dmitry A. Soshnikov wrote:
> On 31.08.2011 18:38, Allen Wirfs-Brock wrote:
>> On Aug 31, 2011, at 1:57 AM, Dmitry A. Soshnikov wrote:
>>
>>> 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.
>> When designing language features, a designer always has some specific 
>> use cases in mind.  But that doesn't restrict users of the language 
>> from discovering other use cases. Once a feature is  incorporated 
>> into a language, implementation have to support all possible use 
>> cases, not just the original intended use case.   That's why it is 
>> important for language designer to think broadly about all 
>> conceivable uses and feature interaction when extending a language. 
>> Sure, no application is required to have logic dependencies upon the 
>> content of a documentation string but once they exist any application 
>> could have such dependencies. As a language designers you have to 
>> think about the implications of such usages.  It isn't good enough to 
>> just say that wasn't the intended use of the feature.
>>
>
> Yes, of course it's true, we have to consider the most hardcore 
> use-cases of our programs. Well, then I have to think on it, but the 
> first thing which comes in mind -- already mentioned "Remove 
> doc-comments" option for minifiers, i.e. a user himself is responsible 
> for this action.


By the way, another solution is to use another prologue directive:

"use documentation";

or vice-versa, "no documentation"; since it would be better to turn-off 
the feature, but by default to have it in the console, tests and debug.

P.S.: want to embed the source-code transformation script I gave into 
Narcissus as an extension (e.g. an option for compilation)?

njs script.js --with-doc

Dmitry.

> Moreover, minification is again mostly for browser-scripting, where 
> this help(...) functionality isn't so required as it is for the server 
> programming in the console.
>
> And for the later case I wrote a simple version of such a 
> pre-processor: https://gist.github.com/1186853
>
> Simple example:
>
> /**
>  * sum
>  * @param {Number} x
>  * @param {Number} y
>  * The function of summation.
>  */
> function sum(x, y) {
>   return x + y;
> }
>
> /**
>  * multSum
>  * @param {Number} x
>  * @param {Number} y
>  * @param {String} value
>  * The function of calculation.
>  */
> function calculate(x, y, value) {
>   // comment
>   print(value + ": " + sum(x, y));
> }
>
> // ---------- Test documentation ----------
>
> // Result:
>
> // Help on "sum" function:
> //
> // /**
> //  * sum
> //  * @param {Number} x
> //  * @param {Number} y
> //  * The function of summation.
> //  */
> help(sum);
>
> // Help on "calculate" function:
> //
> // /**
> //  * multSum
> //  * @param {Number} x
> //  * @param {Number} y
> //  * @param {String} value
> //  * The function of calculation.
> //  */
> help(calculate);
>
> // ---------- Test guards ----------
>
> sum(1, 2); // 3, OK
>
> calculate(1, 2, "value"); // value: 3
>
> sum(1, "2"); // TypeError: "y" must be a number
>
> calculate(1, 2, 4); // TypeError: "value" must be a string
>
> Dmitry.
>



More information about the es-discuss mailing list