__doc__ for functions, classes, objects etc.

Dmitry A. Soshnikov dmitry.soshnikov at gmail.com
Sun Aug 7 09:56:34 PDT 2011


What about to standardize (Python's) "__doc__"-umentation comments for 
JS? Not exactly in this name with underscores, but the idea itself. I 
remember recent discussion on Twitter where Brendan proposed to use a 
prologue string for that:

function foo() {
   "this is the super function"

then having some util which can analyze string decompilation of the 
function shows the documentation: Object.getDocumentation(foo) -> "this 
is the super function".

However, engines usually optimize this case and remove "dead-code". 
Moreover, `toString` for functions is not standardized also. So all 
these are just toys and examples. In contrast -- Python's __doc__ make 
this documentation as a property of function. It can be some internal 
property -- no matter, for that Object.getDoc(fn) will read this 
[[Documentation]] stuff.

Why did I recall it? -- a real practical case -- just installed redis 
k-w database to play and wanted to see the documentation right from the 
node's console -- but... can't. There's no such an ability in JavaScript 
-- which is the best in Python.

So if to accept triple-string and comments we catch two things at once 
(after all, triple-strings are useful by themselves):

function foo() {
   Still the stuff is super.
   @author Me
   And double "quotes" are not needed to escape,
   as well as 'single'

   // implementation


Object.getDoc(foo) -> "Still the stuff is super.\n at author MeAnd double 
\"quotes\" are not needed to escape,\nas well as 'single'"



More information about the es-discuss mailing list