__doc__ for functions, classes, objects etc.

[Irakli Gozalishvili]

On Saturday, 2011-09-03 at 24:55 , Oliver Hunt wrote:

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

Yeap toString is not reliable, but hey it works just fine on most engines I know ;) Also SM strips out dec code that's why I use label hack so that it keeps it :) 

> It also doesn't work for builtin functions, and I feel we'd want a solution that allows documentation for builtin functions as well.
> 
> 
> 


In fact `doc` function will work with built-ins just fine, even though output is not that useful:

> doc(Array.prototype.slice)

> function slice($1, $2) { ... }


> 
> 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/20110903/6acca6fa/attachment.html>