I don't believe JSDoc is part of ES spec, right? It could easily be
something else. We can not infer types at runtime for many functions
in the first place, so what point would the JSDoc have? Consider this
example:
```js
var f = function(arg1, arg2) {
console.log(arg1, arg2)
}
console.log(f)
```
output:
```
/**
* @param {} arg1
* @param {} arg2
*/
function(arg1, arg2) {
console.log(arg1, arg2)
}
```
That's not entirely helpful as the JSDoc doesn't add any info we can
already gain from parsing the function source. I think JSDoc is better
for hand-made cases, where an author defines the usage of the function
manually, f.e.:
```js
/**
* Meaningful description goes here.
*
* @param {String} arg1 Must be a string for some reason.
* @param {Number} arg2 Must be a number for some reason.
* @param {Number} arg3 Arg3 is documented, but not in the parameter
list (completely possible).
* @return {SomeType} Something meaningful is returned.
*/
function(arg1, arg2) {
// ...
}
```
> Could it be doable to add a separate new property or something to a function
> that attaches it's preceding comment content or is a "verbose" toString
> alternative.
Storing these things in a runtime variable just adds more memory
consumption to an app. It can easily be added on a per-app-basis
without requiring it as part of the ES spec. For example, make a Babel
transform if you really want this feature.
On Mon, Apr 18, 2016 at 9:37 AM, Matthew Robb <matthewwr...@gmail.com> wrote:
> Could it be doable to add a separate new property or something to a function
> that attaches it's preceding comment content or is a "verbose" toString
> alternative.
>
>
> - Matthew Robb
>
> On Mon, Apr 18, 2016 at 11:40 AM, Andy Earnshaw <andyearns...@gmail.com>
> wrote:
>>
>> I imagine there's code in the wild that predates function.name, looking
>> something like this:
>>
>> var fooName = foo.toString().match(/^function (\w+)/)[1];
>>
>> If a newer browser adds a preceding comment to the function then this code
>> will break. The top voted answer to a question[1] on Stack Overflow would
>> break if the comment contained the string 'function '.
>>
>> [1]: http://stackoverflow.com/q/2648293
>>
>> On Sun, 17 Apr 2016 at 11:07 Isiah Meadows <isiahmead...@gmail.com> wrote:
>>>
>>> I don't like the idea of including preceding comments in
>>> `Function.prototype.toString` itself on grounds it's harder to parse for
>>> other related reasons.
>>>
>>> As for anything including preceding comments, I'd be happy with something
>>> somewhat independent, as long as it's not requiring JSDoc to be parsed. Not
>>> that I have issues with that documentation format, but I don't think it
>>> should be in the spec itself.
>>>
>>>
>>> On Sat, Apr 16, 2016, 13:29 Jordan Harband <ljh...@gmail.com> wrote:
>>>>
>>>> As I see it, the primary purpose of the `Function#toString` proposal is
>>>> to document what browsers already do, and tighten it down so they can't
>>>> deviate further (which some browsers already have begun to do with "class",
>>>> for example).
>>>>
>>>> "Preceding comments" would be a very hard thing to specify without
>>>> unduly blessing an arbitrary documentation pattern, especially one that
>>>> isn't universally considered to be a good thing.
>>>>
>>>> Reflection methods on functions are certainly a potential separate
>>>> proposal, if you can make a compelling argument that it's a good idea to
>>>> reflect on functions in this manner.
>>>>
>>>> On Sat, Apr 16, 2016 at 9:42 AM, Marius Gundersen <gunder...@gmail.com>
>>>> wrote:
>>>>>
>>>>> Would it not be better to expose the names (and default values,
>>>>> destructurings, etc) of the function arguments using reflection? For
>>>>> example, Reflection.arguments(Math.max).then this method can return any
>>>>> JSDoc it is able to parse.
>>>>>
>>>>> On 16 Apr 2016 16:53, "Caitlin Potter" <caitpotte...@gmail.com> wrote:
>>>>>>
>>>>>> How would that interact with angular.js' Function.prototype.toString
>>>>>> parsing? Seems like doing that could break some content, even if it were
>>>>>> useful
>>>>>>
>>>>>> On Apr 16, 2016, at 10:48 AM, Axel Rauschmayer <rausc...@icloud.com>
>>>>>> wrote:
>>>>>>
>>>>>> Regarding this proposal:
>>>>>> https://github.com/tc39/Function-prototype-toString-revision
>>>>>>
>>>>>> Wouldn’t it make sense to include a preceding JSDoc-style comment in a
>>>>>> function’s (or method’s) `[[SourceText]]` value? Conceptually it is a
>>>>>> part
>>>>>> of the function and it could be used to implement a REPL `help()`
>>>>>> function.
>>>>>>
>>>>>> --
>>>>>> Dr. Axel Rauschmayer
>>>>>> a...@rauschma.de
>>>>>> rauschma.de
>>>>>>
>>>>>> _______________________________________________
>>>>>> es-discuss mailing list
>>>>>> es-discuss@mozilla.org
>>>>>> https://mail.mozilla.org/listinfo/es-discuss
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> es-discuss mailing list
>>>>>> es-discuss@mozilla.org
>>>>>> https://mail.mozilla.org/listinfo/es-discuss
>>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> es-discuss mailing list
>>>>> es-discuss@mozilla.org
>>>>> https://mail.mozilla.org/listinfo/es-discuss
>>>>>
>>>>
>>>> _______________________________________________
>>>> es-discuss mailing list
>>>> es-discuss@mozilla.org
>>>> https://mail.mozilla.org/listinfo/es-discuss
>>>
>>> _______________________________________________
>>> es-discuss mailing list
>>> es-discuss@mozilla.org
>>> https://mail.mozilla.org/listinfo/es-discuss
>>
>>
>> _______________________________________________
>> es-discuss mailing list
>> es-discuss@mozilla.org
>> https://mail.mozilla.org/listinfo/es-discuss
>>
>
>
> _______________________________________________
> es-discuss mailing list
> es-discuss@mozilla.org
> https://mail.mozilla.org/listinfo/es-discuss
>
_______________________________________________
es-discuss mailing list
es-discuss@mozilla.org
https://mail.mozilla.org/listinfo/es-discuss
