__doc__ for functions, classes, objects etc.

Rick Waldron waldron.rick at gmail.com
Sun Aug 21 10:01:50 PDT 2011


This is a great idea, but I wonder if the concept could be implemented using
comments as we already know them? This would leave it up to the user how
they want to parse the property's value. Just a thought - either way, I
think this is a valuable idea.

Rick



On Sun, Aug 7, 2011 at 12:56 PM, Dmitry A. Soshnikov <
dmitry.soshnikov at gmail.com> wrote:

> Hi,
>
> 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'"
>
> Huh?
>
> Dmitry.
> ______________________________**_________________
> es-discuss mailing list
> es-discuss at mozilla.org
> https://mail.mozilla.org/**listinfo/es-discuss<https://mail.mozilla.org/listinfo/es-discuss>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110821/e98daa6f/attachment.html>


More information about the es-discuss mailing list