Function#toString revision: JSDoc comments?
How would that interact with angular.js' Function.prototype.toString parsing? Seems like doing that could break some content, even if it were useful
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.
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.
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.
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 question1 on Stack Overflow would break if the comment contained the string 'function '.
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
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:
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.:
/**
* 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.
Right. That’s a compelling argument against my suggestion.
My initial motivation was to create a Python-style help() function. But I agree that it’s probably better not to depend on this mechanism.
On Sat, Apr 16, 2016 at 7:53 AM, Caitlin Potter <caitpotter88 at 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
Comments are generally a failure of the developer to write self explanatory code.
The proposal to break Angular.JS by having Function.prototype.toString result in preceeding comments could send a message of not relying on Function decompilation (we went over this in 2005; a dead horse), but it won't happen.
Because although code in the wild (for the web) cannot reasonably expect Function.prototype.toString to produce anything other than a string for which eval will throw a SyntaxError, implementations try to meet the unreasonable demands imposed by these libraries and their hapless users (the coders who use Angular in their source code, not the end user).
Not only does it contradict existing spec (something the Angular.js developers obviously didn't bother to read), but it changes what browsers actually do, and if it means breaking the web, browsers won't do that. Even if the vast majority of content served in conjunction with Angular is not useful.
Thank you,
Regarding this proposal: tc39/Function-prototype-toString-revision, 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 REPLhelp()function.