__doc__ for functions, classes, objects etc.

[Oliver Hunt]

On Sep 2, 2011, at 3:41 PM, Brendan Eich wrote:

> On Sep 2, 2011, at 3:29 PM, Irakli Gozalishvili wrote:
> 
>> On Friday, 2011-09-02 at 22:28 , Brendan Eich wrote:
>>> Can you show your label hack for SpiderMonkey to es-discuss?
>>> 
>> 
>> Ahh sorry I did not realized I forgot to post link:
>> 
>> https://github.com/Gozala/doc 
> 
> Cool! Permit me to cite some of your README content to help promote to those who did not click ;-) -- here it is:
> 
> var doc = require('doc').doc
> doc(doc) // Prints following output:
> 
> /*
> function doc(source) { ... }
> -----------------------------------------------
> Prints documentanion of the given function
> */
> 
> // You can also document your own functions:
> 
> function compose() {
>   doc: "Returns the composition of a list of functions, where each function"
>      | "consumes the return value of the function that follows. In math"
>      | "terms, composing the functions `f()`, `g()`, and `h()` produces"
>      | "`f(g(h()))`."
>      | "Usage:"
>      | "var greet = function(name) { return 'hi: ' + name }"
>      | "var exclaim = function(statement) { return statement + '!' }"
>      | "var welcome = compose(exclaim, greet)"
>      | "welcome('moe')"
>      | "//> 'hi: moe!'"

Function.toString isn't standardised, and I recall that in the past SM did elide dead code, multiple engines reformat code, so in general this doesnt seem reliable at a library level.  It also doesn't work for builtin functions, and I feel we'd want a solution that allows documentation for builtin functions as well.

>From the pov of runtime identification, we'd be in the odd position of having to try and identify valid code as being documentation.

This shouldn't be taken as support for this idea (documentation as part of the language) as I feel that this is the type of feature i'd associate with the development environment rather than part of the language.

--Oliver

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110902/0cf538df/attachment.html>